[Announcement] Planning for Swift Atomics v1.0

TLDR: We'd like to officially declare Swift Atomics source stable and tag version 1.0 of it in the next week or two. Please speak up now if you'd like to see something changed before the 1.0 release.

Swift Atomics 1.0

As Swift Atomics gets adopted by more and more projects, it is becoming increasingly unlikely we would be able to make source breaking changes to its API. It makes sense to accept this fact and declare the package source stable now.

Our plan is to tag version 1.0 of swift-atomics in the next week or two.

What do you mean by source stability?

We expect to observe the rules of Semantic Versioning. Changes to the public API of the package that are expected to cause build failures in adopters can only be shipped in a new major release. The same goes for behavioral changes that are likely to change the meaning of existing code in ways that lead to incorrect/unexpected results.

Note: Pretty much every change can technically break someone, so this isn't an exact science. At the end of the day, whether a change introduces acceptable risk boils down to a judgment call made by the package maintainers, based on information supplied by the community. When we get it wrong, I expect we will be able to correct mistakes after the fact by tagging a subsequent new release.

What's considered public API?

The public API of version 1.0 of the swift-atomics package will consist of non-underscored declarations that are marked public in the Atomics module.

By "underscored declarations" we mean declarations that have a leading underscore anywhere in their fully qualified name. For instance, here are some names that wouldn't be considered part of the public API, even if they were technically marked public:

  • FooModule.Bar._someMember(value:)
  • FooModule._Bar.someMember
  • _FooModule.Bar
  • FooModule.Bar.init(_value:)

Underscored APIs may continue to change in any release, including patch releases.

Note that contents of the _AtomicsShims module aren't public API. (As implied by its underscored module name.) The definitions therein may therefore change at whim, and the entire module may be removed in any new release -- directly importing this module isn't recommended.

We also don't make any source compatibility promises about the contents of the Utilities and Tests subdirectories.

Future minor versions of the package may introduce changes to these rules as needed.

How often will we tag a new major release?

Given that this is a core package that is likely to become a dependency of many projects, I expect we will rarely if ever be able to release new major versions of it.

The stated intention of this package is to serve as a proving ground for potential stdlib additions, so we'll have at least one opportunity to make major API changes, at the time we propose these types for addition to the Standard Library.

In the (hopefully unlikely) case that we need to make sweeping API changes before that, we have the option to do that by adding new variants of existing types without removing the original implementations.

So are we stuck with UnsafeAtomic forever?

I don't think so. As the language evolves, we hope to be able to eventually replace the current UnsafeAtomic and ManagedAtomic types with a safer/faster/better construct. However, this doesn't necessarily require a major release bump: we can just add a new construct in a minor release and continue shipping (deprecated) versions of the current types indefinitely. (Or we may decide to bump the major version anyway, and deal with a potentially messy ecosystem transition.)

What about new additions?

New features implemented after 1.0 will ship in subsequent minor releases (1.1, 1.2, etc.) as soon as they're ready.

I expect new additions will become part of the public API as soon as they get included in a tagged release. (Although this may be considered on a case by case basis.)

Adopting new Swift releases

The Swift language hasn't stopped evolving, and we'd like this package to quickly embrace toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to the latest Swift toolchain release. (This allows the package to make use of new language/stdlib features, build on compiler bug fixes, and adopt new package manager functionality as soon as they are available.)

Requiring a new Swift release will only require a minor version bump.

The package manager's dependency resolution engine gracefully handles toolchain versioning, so people who are unable to upgrade their Swift toolchain will be able to continue using older package versions that did support them. We also have the option to support these older versions with back ported bug fixes.

Our expectation is that projects that would be interested in adopting new package features are, as a rule, also likely to upgrade to new toolchain releases. (Requiring a recent toolchain also reflects the reality that most engineering work on the package will be concentrated on targeting the latest Swift release (and development snapshots of the next one). Previous toolchain releases will receive limited testing at best.)

Request for comments

This is likely to be the last opportunity to (easily) fix API design issues in this package, for quite a long time.

If you have noticed API problems with this package, now is the time to complain about them. Please reply to this post with your notes!

No issue is too minor. Did you spot an inconsistent label? Does an operation have an unclear name? Would it be better if we swapped some argument orders? Please post about it -- this may be the last opportunity to fix these things, for quite a while.

Thank you!

10 Likes

It looks like you copied/pasted from the Collections announcement but forgot to update this section.

2 Likes

And the subtitle :slightly_smiling_face:

2 Likes

Thanks for catching these; I updated the text!

Swift Atomics 1.0 is out now!

11 Likes