Site-www: 'Package versioning' page issue

[feinstein]

Page URL: https://dart.dev/tools/pub/versioning.html
Page source: https://github.com/dart-lang/site-www/tree/master/src/tools/pub/versioning.md

Description of issue:

The document fails to explain what + means and when and how to use it, the only mention to it is ambiguous:

and going to 0.1.2+1 indicates a change that doesn’t affect the public API.

Which leads us to think that + should be used always when there's a change that doesn't impact the public API. The fact that this should only be used in pre 1.0.0 versions is implicit and many famous packages, like Provider have versions like 3.0.0+1, which AFAIK is wrong (I made the same confusion myself, until Travis blocked me from submitting a +1 version as a PR and then I learned).

[kwalrath]

@jonasfj agreed that I should make this clearer?

[jonasfj]

Pub uses https://github.com/dart-lang/pub_semver which is based on:
https://semver.org/spec/v2.0.0-rc.1.html, which defines:

1. A build version MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch version or pre-release version. Identifiers MUST be comprised of only ASCII alphanumerics and dash [0-9A-Za-z-]. Build versions satisfy and have a higher precedence than the associated normal version. Examples: 1.0.0+build.1, 1.3.7+build.11.e0f985a.

Using +1 for pre-1.0.0 releases to indicate a minor version is a Dart community specific convention.

Post-1.0.0, I presume the +1 is intended to mean "build version" as is defined in semver 2.0.0-rc.1.

---

In practice I don't know when it makes sense to use +1, personally, I might use if I just fixed typo in the README (I'm not sure that's sane).. but there are reasonable arguments to be made that "build versions" shouldn't be used after 1.0.0.

Maybe it's better to simply discourage 1.x.y+z as suggested in https://github.com/dart-lang/pub/issues/2171. If we one day have a use-case maybe then we change our mind.

/cc: @natebosch

[jonasfj]

side note: I might be enough to simply warn in pub publish rather than documenting it.

[feinstein]

@jonasfj I think a warning on pub publish would be a nice addition, but I there should be also a more opinionated documentation on this, exposing it as a good practice.

We use +1 also on Flutter apps which don't use pub publish, and even though you add it to the flutter tool, people will want to learn more about the warning and the current documentation is incomplete on this, and kinda ambiguous.

[jonasfj]

We use +1 also on Flutter apps which don't use pub publish, and even though you add it to the flutter tool...

The flutter tool uses pub under the hood:
https://flutter.dev/docs/development/packages-and-plugins/developing-packages#publishing-packages
(afaik, it does a few tricks and ensures you're calling the pub version distributed with Flutter).

[feinstein]

Oh ok, well, AFAIK the flutter plugin repo doesn't accept +1 in post 1.0.0 versions, their CI tooling check for this if you guys want to take a look.

[natebosch]

The paragraph quoted is specifically discussing how to version packages with a major version of 0. I'd be in favor of making this more clear by adding a trailing sentence in that paragraph - "The + versions should only be used for non-API changes in packages with a leading 0. version."

IMO we don't need to specifically discuss it's use for build versions.

[feinstein]

I agree that this sentence is desirable as it makes the text intention clearer, but in that case the use of + in anything major version different than 0, will not be addressed in the principal dart documentation regarding versioning, which I think will lead to questions, since we see them being used a lot.

After reading:

"The + versions should only be used for non-API changes in packages with a leading 0. version."

My immediate thought is "ok, then what's the meaning of + in non-0 leading versions, like that package I saw yesterday?

[jonasfj]

@munificent, could we poke you for an opinion on the topic of when to use "build versions" in the package version. We currently have a convention for using the "build versions" as "patch version" in pre-1.0.0 releases.

From: https://github.com/dart-lang/site-www/blob/master/src/tools/pub/versioning.md

Although semantic versioning doesn't promise any compatibility between versions prior to 1.0.0, the Dart community convention is to treat those versions semantically as well. The interpretation of each number is just shifted down one slot: going from 0.1.2 to 0.2.0 indicates a breaking change, going to 0.1.3 indicates a new feature, and going to 0.1.2+1 indicates a change that doesn't affect the public API.

In https://github.com/dart-lang/crypto/pull/68#discussion_r311312191 you suggested increasing the "build version" when publishing a fix that merely repackaged the same code. In https://github.com/dart-lang/pub/issues/2171 it's been suggested that we discourage "build version" for any post-1.0.0 releases.

@munificent, do you have an opinion here? Should we:
(A) discourage using "build version" in post-1.0.0 releases, or,
(B) guide developers to only use "build version" in post-1.0.0 releases for scenarios such as:

• Repackaging the same code (e.g. removing a file accidentally included)
• Rebuilding binary blobs, images, videos, etc. embedded in the package
• Modifying README / CHANGELOG / examples
• Relaxing version constraints in pubspec.yaml
• Changing metadata (such as description") in pubspec.yaml
• Changes that doesn't change the code
• Changes to documentation comments

I think it's clear that we should strongly discourage using a "build version" bump when changing code in post-1.0.0 releases. And since there's little value in distinguishing between a "patch version bump" and a "build version bump", we could just outright discourage "build version bumps".

[munificent]

(B) is what we've done and encouraged people to do in the past. Personally, I'm fine with moving towards (A) since it's simpler.

[kwalrath]

Should I change the docs or close this?

[jonasfj]

In:

Although semantic versioning doesn’t promise any compatibility between versions prior to 1.0.0, the Dart community convention is to treat those versions semantically as well. The interpretation of each number is just shifted down one slot: going from 0.1.2 to 0.2.0 indicates a breaking change, going to 0.1.3 indicates a new feature, and going to 0.1.2+1 indicates a change that doesn’t affect the public API.

We could add a small sentence like:

Besides use in 0.x.y+z it's often preferable to avoid +build-metadata for simplicity.

Please feel free reword, this phrasing is not the best :)

But don't think we necessarily must make huge deal out of explaining what +build-metadata is, or when it's appropriate to use. Or that it's preferable to avoid using +build-metadata because it can confuse some users. A single line saying that _to keep it simple_ it is _often preferable_ to avoid using build metadata.

If we want to be any stronger it's better to add a warning in pub publish.