Bump version metadata to produce correct tester and nightly build precedence #1492
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Previously the instructions for updating the npm package metadata, submitting a PR for that, and merging the PR was in the same section as the tag push instructions in the release procedure documentation. These two operations are distinct from each other. Mashing them into a single step makes the release procedure document difficult to read and the process more prone to error. For this reason, a dedicated step is used for each of the two things.
The release procedure is a set of steps which must be performed in a specific sequence. This fact is more effectively communicated by formatting it as an ordered list.
…version precedence
On every startup, the Arduino IDE checks for new versions of the IDE. If a newer version is available, a
notification/dialog is shown offering an update.
"Newer" is determined by comparing the version of the user's IDE to the latest available version on the update channel.
This comparison is done according to the Semantic Versioning Specification ("SemVer").
In order to facilitate beta testing, builds are generated of the Arduino IDE at the current stage in development. These
builds are given an identifying version of the following form:
- <version>-snapshot-<short hash> - builds generated for every push and pull request that modifies relevant files
- <version>-nightly-<YYYYMMDD> - daily builds of the tip of the default branch
The previous release procedure caused the <version> component of these to be the version of the most recent release.
During the pre-release phase of the project development, all releases had a pre-release suffix (e.g., 2.0.0-rc9.4).
Appending the "snapshot" or "nightly" suffix to that pre-release version caused these builds to have the correct
precedence (e.g., 2.0.0-rc9.2.snapshot-20cc34c > 2.0.0-rc9.2). This situation has changed now that the project is using
production release versions (e.g., 2.0.0-nightly-20220915 < 2.0.0). This caused users of "snapshot" or "nightly" builds
to be presented with a spurious update notification on startup.
The solution is to add a step to the end of the release procedure to do a minor bump of the version metadata after
creating the release tag.
This means that the metadata bump traditionally done before the creation of the release tag will already have been done
in advance for patch releases. However, it will still need to be done for minor or major releases.
The release procedure documentation is hereby updated to produce correct tester and nightly build version precedence.
The metadata bump step is moved from before to after the tag creation step, replaced by a new step to verify the version
before the tag creation, updating it in the event it is not a patch release. Both those steps may require updating the
metadata. As an alternative to maintaining duplicate copies, each step links to a single copy of the fairly complex
instructions for doing so. The structure of the document is adjusted to accomodate this, by placing the steps of the
procedure under a "Steps" section and creating a new "Operations" section to contain any such shared content.
…cedence
On every startup, the Arduino IDE checks for new versions of the IDE. If a newer version is available, a
notification/dialog is shown offering an update.
"Newer" is determined by comparing the version of the user's IDE to the latest available version on the update channel.
This comparison is done according to the Semantic Versioning Specification ("SemVer").
In order to facilitate beta testing, builds are generated of the Arduino IDE at the current stage in development. These
builds are given an identifying version of the following form:
- <version>-snapshot-<short hash> - builds generated for every push and pull request that modifies relevant files
- <version>-nightly-<YYYYMMDD> - daily builds of the tip of the default branch
The previous release procedure caused the <version> component of these to be the version of the most recent release.
During the pre-release phase of the project development, all releases had a pre-release suffix (e.g., 2.0.0-rc9.4).
Appending the "snapshot" or "nightly" suffix to that pre-release version caused these builds to have the correct
precedence (e.g., 2.0.0-rc9.2.snapshot-20cc34c > 2.0.0-rc9.2). This situation has changed now that the project is using
production release versions (e.g., 2.0.0-nightly-20220915 < 2.0.0). This caused users of "snapshot" or "nightly" builds
to be presented with a spurious update notification on startup.
The solution is to do a minor bump of the version metadata after creating the release tag. That was not done immediately
following the 2.0.0 release. The omission is hereby corrected.
This will provide the metadata bump traditionally done before the creation of the release tag in the event the version
number of the next release is 2.0.1. In case it is instead a minor or major release, the version metadata will need to
be updated once more before the release tag is created.
Contributor are presented with an issue template chooser page at the start of the issue creation process. In addition to the issue report templates, some "contact links" provide information and links to other communication channels. In order to encourage high quality issues, a link to the "issue report guide" is included on this page. Previously that link pointed to an incorrect URL, resulting in a 404 error for those who visited it. The URL is hereby corrected.
per1234
added
topic: documentation
kittaakos
approved these changes
Sep 26, 2022
|
|
||
| If the version number of the previous release was `2.0.1`: | ||
|
|
||
| - If this is considered a minor release (non-breaking changes to the "API"), the `version` values must be changed to `2.1.0`. |
There was a problem hiding this comment.
IDE2 never followed semver, and does not expose any public APIs, but we can leave this in the doc. In the end, the desired version is a marketing-only thing.
There was a problem hiding this comment.
Notice that I put "API" in quotes. The spirit of SemVer can still be applied even to projects which don't have a traditional API. The idea of SemVer is that the version number conveys meaning to the users. It is an unfortunate fact that version numbers are sometimes manipulated for marketing purposes, but this is documentation for maintainers, not marketers.
Most often, the choice of version number will be at the discretion of the maintainer and that maintainer should base the choice purely on technical considerations.
| ## 📄 Create the changelog | ||
| ### 4. ⬆️ Bump version metadata of packages | ||
|
|
||
| In order for the version number of the tester and nightly builds to have correct precedence compared to the release version, the `version` field of the project's `package.json` files must be given a patch version bump (e.g., `2.0.1` -> `2.0.2`) **after** the creation of the release tag. |
There was a problem hiding this comment.
In the long run, we should use yarn to generate these pre-release version numbers instead of manually bumping them. Once this is merged, I will create a follow-up with the request.
Ref: https://classic.yarnpkg.com/en/docs/cli/version/#toc-yarn-version-prerelease
| git checkout -b version-<YOUR_VERSION> | ||
| yarn update:version <YOUR_VERSION> | ||
| git commit -am <YOUR_VERSION> | ||
| git push origin version-<YOUR_VERSION> |
There was a problem hiding this comment.
Assuming you have set the remote to origin.
There was a problem hiding this comment.
This pull request only moved the existing content from one place in the document to another.
3 tasks
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
On every startup, the Arduino IDE checks for new versions of the IDE (#797). If a newer version is available, a notification/dialog is shown offering an update.
"Newer" is determined by comparing the version of the user's IDE to the latest available version on the update channel. This comparison is done according to semver.
In order to facilitate beta testing, builds are generated of the Arduino IDE at the current stage in development. These builds are given an identifying version of the following form:
<version>-snapshot-<short hash>- builds generated for every push and pull request that modifies relevant files<version>-nightly-<YYYYMMDD>- daily builds of the tip of the default branchThe established project management practices cause the
<version>component of these to be the version of the most recent release.During the pre-release phase of the project development, all releases had a pre-release suffix (e.g.,
2.0.0-rc9.4). Appending the "snapshot" or "nightly" suffix to that pre-release version caused these builds to have the correct precedence (e.g.,2.0.0-rc9.2.snapshot-20cc34c>2.0.0-rc9.2). This situation has changed now that the project is using production release versions (e.g.,2.0.0-nightly-20220915<2.0.0). This causes users of "snapshot" or "nightly" builds to be presented with a spurious update notification on startup (#1440).Change description
The solution is to do a minor bump of the version metadata after creating the release tag.
versionfield in the project'spackage.jsonmetadata files to2.0.1Other information
The rendered release procedure document can be previewed here:
https://github.com/per1234/arduino-ide/blob/bump-after-release/docs/internal/release-procedure.md#readme
Fixes #1440
The pull request also contains an unrelated fix to the link to the "Issue Report Guide" from the issue template chooser page, which was previously broken.
Reviewer checklist