From c08cf3d97e8a647cc8505b52d4a2a565567c7d41 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sat, 24 Sep 2022 16:36:18 -0700 Subject: [PATCH 1/5] Move package metadata update step to dedicated section of release docs 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. --- docs/internal/release-procedure.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/internal/release-procedure.md b/docs/internal/release-procedure.md index b95916367..5cf1f8349 100644 --- a/docs/internal/release-procedure.md +++ b/docs/internal/release-procedure.md @@ -10,9 +10,9 @@ It will be shown in these search results: https://github.com/arduino/arduino-ide/pulls/app%2Fgithub-actions -## βš™ Create the release on GitHub +## βš™ Update metadata of packages -First of all, you need to **set the new version in all the `package.json` files** across the app (`./package.json`, `./arduino-ide-extension/package.json`, and `./electron-app/package.json`), create a PR, and merge it on the `main` branch. +You need to **set the new version in all the `package.json` files** across the app (`./package.json`, `./arduino-ide-extension/package.json`, and `./electron-app/package.json`), create a PR, and merge it on the `main` branch. To do so, you can make use of the `update:version` script. @@ -29,6 +29,8 @@ git push origin version- replacing `` with the version you want to release. Then create a PR and merge it. +## 🚒 Create the release on GitHub + Then, you need to **create and push the new tag** and wait for the release to appear on [the "**Releases**" page](https://github.com/arduino/arduino-ide/releases). ⚠ Doing this will create a new release and users who already have the IDE installed will be notified from the automatic updater that a new version is available. Do not push the tag if you don't want that. From 6833c91229a419982ed3d7500b7793aed47e6cc8 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sat, 24 Sep 2022 17:00:36 -0700 Subject: [PATCH 2/5] Format release procedure document as ordered list 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. --- docs/internal/release-procedure.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/internal/release-procedure.md b/docs/internal/release-procedure.md index 5cf1f8349..ee5b3cdf1 100644 --- a/docs/internal/release-procedure.md +++ b/docs/internal/release-procedure.md @@ -1,6 +1,6 @@ # Release Procedure -## πŸ—ΊοΈ Merge localization sync PR +## 1. πŸ—ΊοΈ Merge localization sync PR A pull request titled "**Update translation files**" is submitted periodically by the "**github-actions**" bot to pull in the localization data from [**Transifex**](https://www.transifex.com/arduino-1/ide2/dashboard/). @@ -10,7 +10,7 @@ It will be shown in these search results: https://github.com/arduino/arduino-ide/pulls/app%2Fgithub-actions -## βš™ Update metadata of packages +## 2. βš™ Update metadata of packages You need to **set the new version in all the `package.json` files** across the app (`./package.json`, `./arduino-ide-extension/package.json`, and `./electron-app/package.json`), create a PR, and merge it on the `main` branch. @@ -29,7 +29,7 @@ git push origin version- replacing `` with the version you want to release. Then create a PR and merge it. -## 🚒 Create the release on GitHub +## 3. 🚒 Create the release on GitHub Then, you need to **create and push the new tag** and wait for the release to appear on [the "**Releases**" page](https://github.com/arduino/arduino-ide/releases). @@ -44,7 +44,7 @@ git push origin Pushing a tag will trigger a **GitHub Actions** workflow on the `main` branch. Check the "**Arduino IDE**" workflow and see that everything goes right. If the workflow succeeds, a new release will be created automatically and you should see it on the ["**Releases**"](https://github.com/arduino/arduino-ide/releases) page. -## πŸ“„ Create the changelog +## 4. πŸ“„ Create the changelog **Create GitHub issues for the known issues** that we haven't solved in the current release: @@ -63,7 +63,7 @@ Add a list of mentions of GitHub users who contributed to the release in any of Add a "**Known Issues**" section at the bottom of the changelog. -## ✎ Update the "**Software**" Page +## 5. ✎ Update the "**Software**" Page Open a PR on the [bcmi-labs/wiki-content](https://github.com/bcmi-labs/wiki-content) repository to update the links and texts. @@ -80,7 +80,7 @@ When the deploy workflow is done, check if links on the "**Software**" page are https://www.arduino.cc/en/software#future-version-of-the-arduino-ide -## 😎 Brag about it +## 6. 😎 Brag about it - Ask in the `#product_releases` **Slack** channel to write a post for the social media and, if needed, a blog post. - Post a message on the forum (ask @per1234).
From 751114ad408d6e34098496c422535b2d95bee3f8 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sat, 24 Sep 2022 17:27:04 -0700 Subject: [PATCH 3/5] Adjust release procedure to produce correct tester and nightly build 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: - -snapshot- - builds generated for every push and pull request that modifies relevant files - -nightly- - daily builds of the tip of the default branch The previous release procedure caused the 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. --- docs/internal/release-procedure.md | 69 ++++++++++++++++++++++-------- 1 file changed, 51 insertions(+), 18 deletions(-) diff --git a/docs/internal/release-procedure.md b/docs/internal/release-procedure.md index ee5b3cdf1..12afe0e26 100644 --- a/docs/internal/release-procedure.md +++ b/docs/internal/release-procedure.md @@ -1,6 +1,10 @@ # Release Procedure -## 1. πŸ—ΊοΈ Merge localization sync PR +## Steps + +The following are the steps to follow to make a release of Arduino IDE: + +### 1. πŸ—ΊοΈ Merge localization sync PR A pull request titled "**Update translation files**" is submitted periodically by the "**github-actions**" bot to pull in the localization data from [**Transifex**](https://www.transifex.com/arduino-1/ide2/dashboard/). @@ -10,26 +14,24 @@ It will be shown in these search results: https://github.com/arduino/arduino-ide/pulls/app%2Fgithub-actions -## 2. βš™ Update metadata of packages +### 2. πŸ‘€ Check version of packages -You need to **set the new version in all the `package.json` files** across the app (`./package.json`, `./arduino-ide-extension/package.json`, and `./electron-app/package.json`), create a PR, and merge it on the `main` branch. +The [`version` field](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#version) of the project's `package.json` metadata files received a patch version bump (e.g., `2.0.1` -> `2.0.2`) at the time of the previous release. -To do so, you can make use of the `update:version` script. +If this is a patch release, the current metadata values are correct and no action is needed. -For example, if you want to release the version ``, you should run the following commands: +The changes contained in this release might be considered to change the project's "API". If so, a patch version bump will not be appropriate and the version must be adjusted in compliance with the [**Semantic Versioning Specification**](https://semver.org/). -```text -git checkout main -git pull -git checkout -b version- -yarn update:version -git commit -am -git push origin version- -``` +Follow the instructions for updating the version metadata [**here**](#update-version-metadata). + +#### Examples + +If the version number of the previous release was `2.0.1`: -replacing `` with the version you want to release. Then create a PR and merge it. +- If this is considered a minor release (non-breaking changes to the "API"), the `version` values must be changed to `2.1.0`. +- If this is considered a major release (breaking changes to the "API"), the `version` values must be changed to `3.0.0`. -## 3. 🚒 Create the release on GitHub +### 3. 🚒 Create the release on GitHub Then, you need to **create and push the new tag** and wait for the release to appear on [the "**Releases**" page](https://github.com/arduino/arduino-ide/releases). @@ -44,7 +46,13 @@ git push origin Pushing a tag will trigger a **GitHub Actions** workflow on the `main` branch. Check the "**Arduino IDE**" workflow and see that everything goes right. If the workflow succeeds, a new release will be created automatically and you should see it on the ["**Releases**"](https://github.com/arduino/arduino-ide/releases) page. -## 4. πŸ“„ 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. + +Follow the instructions for updating the version metadata [**here**](#update-version-metadata). + +### 5. πŸ“„ Create the changelog **Create GitHub issues for the known issues** that we haven't solved in the current release: @@ -63,7 +71,7 @@ Add a list of mentions of GitHub users who contributed to the release in any of Add a "**Known Issues**" section at the bottom of the changelog. -## 5. ✎ Update the "**Software**" Page +### 6. ✎ Update the "**Software**" Page Open a PR on the [bcmi-labs/wiki-content](https://github.com/bcmi-labs/wiki-content) repository to update the links and texts. @@ -80,7 +88,7 @@ When the deploy workflow is done, check if links on the "**Software**" page are https://www.arduino.cc/en/software#future-version-of-the-arduino-ide -## 6. 😎 Brag about it +### 7. 😎 Brag about it - Ask in the `#product_releases` **Slack** channel to write a post for the social media and, if needed, a blog post. - Post a message on the forum (ask @per1234).
@@ -99,3 +107,28 @@ https://www.arduino.cc/en/software#future-version-of-the-arduino-ide > > To see the details, you can take a look at the [Changelog](https://github.com/arduino/arduino-ide/releases/tag/2.0.0-beta.12) > If you want to post about it on social media and you need more details feel free to ask us on #team_tooling! :wink: + +## Operations + +The following are detailed descriptions of operations performed during the release process: + + + +### βš™ Update version metadata of packages + +You need to **set the new version in all the `package.json` files** across the app (`./package.json`, `./arduino-ide-extension/package.json`, and `./electron-app/package.json`), create a PR, and merge it on the `main` branch. + +To do so, you can make use of the `update:version` script. + +For example, if you want to update the version to ``, you should run the following commands: + +```text +git checkout main +git pull +git checkout -b version- +yarn update:version +git commit -am +git push origin version- +``` + +replacing `` with the version you want. Then create a PR and merge it. From 34ac7270f9d4297d8e070e90f4e15263b56e540d Mon Sep 17 00:00:00 2001 From: per1234 Date: Sat, 24 Sep 2022 17:49:04 -0700 Subject: [PATCH 4/5] Bump version metadata to produce correct tester and nightly build 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: - -snapshot- - builds generated for every push and pull request that modifies relevant files - -nightly- - daily builds of the tip of the default branch The previous release procedure caused the 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. --- arduino-ide-extension/package.json | 2 +- electron-app/package.json | 4 ++-- package.json | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/arduino-ide-extension/package.json b/arduino-ide-extension/package.json index ac951c619..90f97bfa0 100644 --- a/arduino-ide-extension/package.json +++ b/arduino-ide-extension/package.json @@ -1,6 +1,6 @@ { "name": "arduino-ide-extension", - "version": "2.0.0", + "version": "2.0.1", "description": "An extension for Theia building the Arduino IDE", "license": "AGPL-3.0-or-later", "scripts": { diff --git a/electron-app/package.json b/electron-app/package.json index c2e71bc24..1e26d5c74 100644 --- a/electron-app/package.json +++ b/electron-app/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "electron-app", - "version": "2.0.0", + "version": "2.0.1", "license": "AGPL-3.0-or-later", "main": "src-gen/frontend/electron-main.js", "dependencies": { @@ -21,7 +21,7 @@ "@theia/process": "1.25.0", "@theia/terminal": "1.25.0", "@theia/workspace": "1.25.0", - "arduino-ide-extension": "2.0.0" + "arduino-ide-extension": "2.0.1" }, "devDependencies": { "@theia/cli": "1.25.0", diff --git a/package.json b/package.json index 9800d23e7..39668095b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "arduino-ide", - "version": "2.0.0", + "version": "2.0.1", "description": "Arduino IDE", "repository": "https://github.com/arduino/arduino-ide.git", "author": "Arduino SA", From 43338414436034d5696b8b06c4d756d62cfbf1d0 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sat, 24 Sep 2022 18:03:48 -0700 Subject: [PATCH 5/5] Correct issue report guide link in issue template chooser 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. --- .github/ISSUE_TEMPLATE/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index e87427856..7c038ddf4 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -9,7 +9,7 @@ contact_links: url: https://forum.arduino.cc/ about: We can help you out on the Arduino Forum! - name: Issue report guide - url: https://github.com/arduino/arduino-ide/blob/main/docs/issues.md#issue-report-guide + url: https://github.com/arduino/arduino-ide/blob/main/docs/contributor-guide/issues.md#issue-report-guide about: Learn about submitting issue reports to this repository. - name: Contributor guide url: https://github.com/arduino/arduino-ide/blob/main/docs/CONTRIBUTING.md#contributor-guide