Establish versioning strategy.

[afshin]

Goals

Because JupyterLab relies on the goodwill of early testers, alpha users, and extension authors, we need to try as hard as possible to reward these community members with new features and endeavor to limit breakage as much as possible. Correct use of semantic versioning is a necessary but insufficient part of achieving this.

Extensions

Extensions will require the jupyterlab package from npm, which means that extension authors will be able to specify the version range that their extensions support.

Before we have an extension loading system

Currently, we have used the "identifier" portion of a semantic version in the master branch between releases:

0.1.3-alpha.0 (i.e., the -alpha.0 portion of this version)

However, this has caused extensions that require 0.1.x or ^0.1.2, etc., to detect a mismatch and the built webpack bundle has consequently contained multiple versions of JupyterLab. This has not caused a build error and instead has generated a run-time error.

This means that at the moment, if we use optional identifiers in our versions, all users of master and all extension authors will end up with broken application state. So until we have the new extension system, use of the identifier portion of semantic versioning should be discontinued. Otherwise we will effectively be punishing the users and testers of the bleeding edge.

But this problem is going away.

After we have an extension loading system

When the new extension system is ready to go, extensions will be loaded by the server. The server will be able to check what the current version of JupyterLab is and it will be able to use the "loose" interpretation of semantic versioning, in effect discarding the identifier portion of the version. So our earlier example: 0.1.3-alpha.0 will be interpreted as 0.1.3 which will match the constraints that an extension will be using (e.g., 0.1.x or ^0.1.2).

This frees us to create -rc.1, .rc-2, etc., releases without worrying about breaking things for extension authors or for users of the master branch. An extension author who wants to test against the latest code will be able to check out master and rely on the semantic versioning constraints to just work.

Versioning between releases

Because it is never clear whether our next release will be a patch, a minor release, or a major release, I would propose that the version number in the master branch's package.json file reflect the currently released version. The semantic versioning spec is not prescriptive about this and if we adopt another policy, that's alright, but it seems to me that until we know exactly what our next version is going to be, there's no point in creating a preemptive version string that we may have to roll back upon discovery of a last-second patch or roll forward upon discovery that no new patch was needed before jumping major or minor numbers.

cf. #225

[jasongrout]

Also cf. semver/semver#200 and semver/semver#124.

[jasongrout]

+1 to not using prerelease versions (i.e., the -alpha.N postfix) for the time being. I'm not sure it's a good idea (in that it may cause confusion) to change semver policies with respect to the prerelease version compatibility, but we can decide for sure when we can have 3rd party extensions. I also like the purity of the idea of using an incremented version number just after we release (nominally a patch increment, but when a breaking change is made, incrementing the minor or major versions), but as you can see on the semver issues I linked above, there is a lot of discussion about how to do that. One interesting idea was to (ab)use the build postfix (+dev.N) for this.

[afshin]

I'm open to other strategies than the one I outlined, but I would argue against doing any very "clever" like using postfixes in a nonstandard way.

Your other suggestion of using an incremented patch is at least non-magical (:zap: + :sparkles:), which I find preferable.

[jasongrout]

By the way, that's essentially what we did in this last release - we released 0.1.2, and we ended up incrementing the patch level to 0.1.3.

I'm generally -1 on abusing the system (i.e., making build information to actually indicate changes...), so I'm agreeing with you there.

[blink1073]

cf jupyter/dashboards_server#275 (comment), we need to be careful about making patch releases that affect downstream users.

[svenefftinge]

+1 on incrementing the patch level right after every release. Otherwise it is not possible for downstream consumers to communicate through the version that they depend on the latest HEAD.

[afshin]

@svenefftinge That's a good point, I hadn't considered that extension authors might build extensions that are dependent on master and not on published versions.

[parente]

I'll give this a read. @jhpedemonte might want to also.

[parente]

I agree with incrementing the patch number on master immediately after a release. How about adding the following rule to account for breaking changes ahead of 1.0:

Before cutting a release from master, if there are breaking changes since the patch number was last incremented, commit an increment to the minor number. Then make the release.

This helps prevent unexpected breaks like jupyter/dashboards_server#275. I'm not sure if it helps or hurts packages that want to depend on master HEAD.

[afshin]

@parente I would actually take it one step further: as soon as you know you're committing breaking changes, even before a release, I would propose that very first PR that has the breaking changes should include the version bump in it. That way if it is not merged, no harm done, but if it is, the master version will reflect its level of compatibility with the existing ecosystem.

[parente]

@afshin That works too, as long as you can coordinate one minor version bump per release across everyone making breaking changes.

[SylvainCorlay]

There is a small risk to incremement it more than once though if there are
multiple backward incompatible changes.

On Aug 3, 2016 6:03 AM, "Afshin Darian" notifications@github.com wrote:

@parente https://github.com/parente I would actually take it one step
further: as soon as you know you're committing breaking changes, even
before a release, I would propose that very first PR that has the breaking
changes should include the version bump in it. That way if it is not
merged, no harm done, but if it is, the master version will reflect its
level of compatibility with the existing ecosystem.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#566 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACSXFhChbFBlsL4bne4rcX4IOTlF-jnJks5qcBMggaJpZM4JXYoX
.

[akosyakov]

@afshin In the case if you have nightly builds(#665)
the version between releases should be different from the latest release.

[afshin]

@akosyakov For nightly builds, we can use the identifier portion of the version once we have a plugin build system. Before then, any build that uses identifiers is going to break builds, so we're probably going to hold off on nightly builds until plugins are ready.

[jasongrout]

very first PR that has the breaking changes should include the version bump in it

I think version bumps should be done in master, after a PR is merged, not in PRs. Otherwise we get into situations where multiple PRs have multiple increments, depending on when they were started, and the merge order makes the version number jump around.

@minrk, if I recall correctly, you had a system for doing this and have the version bump tested in CI before merging. How did you do that?

[minrk]

I think what you are referring to is the way I typically build a release:

• bump version, commit (to master, or 4.x, etc.)
• push to my repo, not jupyter or ipython
• this triggers CI, which I have enabled on my fork, in addition to the main repo
• tag, push to jupyter once CI finishes on my branch

I think it's generally fine to bump versions in PRs if people are more comfortable with that, but we don't usually do it that way in other repos. Version bump PRs shouldn't be outstanding for long at all (in particular, they probably shouldn't do anything but bump version), so I wouldn't worry about multiple outstanding version bumps or anything.

[jasongrout]

Version bump PRs shouldn't be outstanding for long at all (in particular, they probably shouldn't do anything but bump version), so I wouldn't worry about multiple outstanding version bumps or anything.

I think the proposal under discussion was bumping version number in the PR making the breaking changes. If there is a specific PR for bumping a version, then it's -0 for me (and +0 if the merge for that PR is a fast-forward merge).

[ellisonbg]

Needs a bit more discussion...

[jasongrout]

@afshin, @blink1073, @ellisonbg, and I discussed this. @blink1073 brought up that many npm packages use the "bump just before release" model, with the understanding that if you are running a dev version, you should use a git commit hash or the github URL to pull down changes since the version was released.

[blink1073]

For example, Backbone has v1.3.3 in their package.json file, but it was released a dozen commits and a few months ago.

[blink1073]

OTOH, CodeMirror takes the approach of bumping a patch version after a release: codemirror/codemirror5@08b8b7b

[blink1073]

Consistency is great: jQuery uses a -pre tag: jquery/jquery@93f7062

[afshin]

Decision

At the Jupyter Lab dev meeting, we decided that we should bump the version number immediately before a release.

The idea is that an extension author who wants to test against the development version will only have issues if there is an actual incompatibility in the dev version ... which would have happened whether the version had been changed or not, but the default scenario will be that an extension author who wants to test an extension against master and has no incompatibilities will have a smoother path.