[META] Plan for publishing null-safe core packages

[kevmoo]

Tracking issue for the plan to publish null-safe core packages.

WIP with @natebosch and @jakemac53

[jcollins-g]

FYI: Dartdoc needs to know about the planned allow-list of null-safe core packages for the tech preview to make sure they are documented correctly. See dart-lang/dartdoc#2211

[kevmoo]

See go/dart-null-safety-1st-party-package-publish-plan

[mit-mit]

@kevmoo can we close this? I believe we have a plan, right?

[natebosch]

I don't think we have a settled plan for all packages. We have a plan for packages pinned by flutter. For the rest there is still open questions around whether we'll do breaking version bumps by default. Last we spoke I think @leafpetersen still wanted to push for non-breaking releases and I'm strongly in favor of breaking releases.

[mit-mit]

This comment details how to handle packages migrated to null safety prior to launch. The term 'trial-migrated' is used to refer to a package that has been migrated during this stage. These migrations are 'trial' by definition, as the null safety isn't guaranteed to be API stable until we reach stable (although the actual API churn is expected to slow down as we approach launch).

Problem statement

We need a solution where:

1. Packages that have been trial-migrated can be published on pub.dev (as the alternative of relying on git-dependencies + overrides is too cumbersome).
2. Developers who are using the null safety experiment (i.e. dev release with a flag), or a null safety beta release (i.e. without a flag), can opt-in to resolve to a package that has been trial-migrated.
3. Developers who are not using null safety don't get resolved to trial-migrated packages without their consent, even if they use those same dev or beta channel releases (which contain null safety support).

Proposed solution for package versioning

Publishing prior to null safety beta

Prior to beta, publishing to pub.dev is strongly discouraged. Doing so, even as a pre-release version, can in some cases lead to pub resolving to the null safety version for a consumer that is not yet using null safety. If that happens, they will be broken.

Thus, prior to beta, we recommend that any trial migrated packages are consumed via git dependencies to the package source code, and that this code is in a branch called null_safety.

The only exception to this role is for a small selection of core packages owned by the core Dart team. Backwards compatible versions of these can be published with extreme care, and only after being added to an allow-list that ensures they work when consumed even without the experiment flag.

Publishing after null safety beta

Once null safety is no longer behind an experimental flag, but prior to the stable launch of the feature, publishing to pub.dev can happen. The below listed steps for versioning must be followed to ensure the null safety version only reaches developers who are ready for it.

Versioning

1. Package version must be with a pre-release version (docs), using nullsafety as the suffix (e.g. 2.0.0-nullsafety.0)

2. Package version must be a major version increment of the most recent stable version on pub.dev (e.g., if most recent stable version is 2.4.0, publish first null safety version as 3.0.0-nullsafety.0). If your package has not already reached 1.0.0, then the package version should be a minor version increment. So if the most recent stable published version is 0.2.4, your first null safety version would be 0.3.0-nullsafety.0.

3. Subsequent updates to the null safety version of the package are handled by incrementing the pre-release suffix p in x.y.z-nullsafety.p (e.g., if first null safety version is 3.0.0-nullsafety.0, use 3.0.0-nullsafety.1 for the next null safety version)

4. Must use a tight SDK constraint that only allows non-stable SDK releases. For example, if the trial migration was done with Dart SDK version 2.11.0-18.0.dev, use:

   • A lower constraint matching the SDK version that was used for the migration, e.g.
     sdk: '>=2.11.0-18.0.dev <2.11.0'

   • An upper constraint that allows subsequent non-stable SDKs, but not the following stable SDK, e.g.
     sdk: '>=2.11.0-18.0.dev <2.11.0'
     This ensures that the pre-release version never get's resolved by a stable SDK release.

Proposed Dart platform support

The above package versioning guidance is supplemented by:

1. A pub client warning which identifies when a package potentially depends on an experimental feature (i.e. that it has a lower SDK constraint which is a non-stable SDK) yet has an upper SDK constraint that allows a stable release

2. The existing pub.dev support for pre-releases (e.g. characters version 1.1.0-nullsafety.2), potentially augmented with support for analyzing packages correctly when they don't use stable SDKs (no earlier than null safety beta)

3. no planned changes to current pub resolution logic (we believe this isn't needed if the guidance above is followed).

[jakemac53]

The more I think about this the less comfortable I am with it. There could be any number of unforeseen circumstances which end up with users picking up a null safety release without intending to.

If we don't want or aren't able to put the time into some solution that actually prevents users from getting these packages at all, then I would prefer to just use git overrides.

[natebosch]

1. as the alternative of relying on git-dependencies + overrides is too cumbersome

How are we determining this? We know that it is cumbersome, but I don't know the criteria we are using to determine how cumbersome it can or should be. If it's because we think it will dissuade users from trying it and we'll have too little feedback my gut instinct goes against that and I wonder if we can find out whether that is true (or delay an implementation of something different until we find it is true).

[jonasfj]

How are we determining this?

I suppose that if we suggest people use git-dependencies on a null-safety branch, then there wouldn't necessarily be a need for dependency_overrides? (as all dependencies also have to migrate and use git dependencies).

[mit-mit]

There could be any number of unforeseen circumstances which end up with users picking up a null safety release without intending to

@jakemac53 Can you exemplify this concern? I simply don't see how it could happen without the user opting-in by updating their pubspec.yaml to allow the new major release. And even in that case it will fail fast (they should get analysis errors quickly), and it's easy to revert (just change the pubspec back).

[mit-mit]

How are we determining this? We know that it is cumbersome, but I don't know the criteria we are using to determine how cumbersome it can or should be.

It's a qualified guess. If trial migration is hard, we'll get fewer doing it, and thus less feature validation. This is a significant risk (to both feature quality and timelines), so we need to weigh that risk against the risk of the proposal I summarized.