1 thought on “[META] Plan for publishing null-safe core packages

  1. 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).

Comments are closed.