Adjust release procedure and CI system for "trunk-based" development strategy

per1234 · per1234 · commit cf93c82283fe · 2023-06-30T09:22:21.000-07:00
Previously, releases were always made from a point in the revision history of the `main` branch (typically the tip of the branch at the time of the release). Although the simplicity of this approach is nice, it can be limiting in some cases. For this reason, the project is switching to using a "trunk-based" development strategy, as described here: https://trunkbaseddevelopment.com/ This approach allows making releases at any time that consist of the arbitrary subset of revisions suitable for shipping to the users at that time. The commits that should be included in the release are cherry-picked to a release branch and the tag created on that branch. This means that: - PRs can be merged to the `main` branch as soon as they have passed review rather than having to postpone the merge of changes that are not ready to be included in the next release. - Releases don't need to be postponed if the prior revision history on the `main` branch contains changes that are not ready to be included in the release. The documented release procedure must be adjusted to reflect the new development strategy. CI System Adjustments --------------------- The status of the GitHub Actions workflows should be evaluated before making a release. However, this is not so simple as checking the status of the commit at the tip of the release branch. The reason is that, for the sake of efficiency, the workflows are configured to run only when the processes are relevant to the trigger event (e.g., no need to run unit tests for a change to the readme). In the case of the default branch, you can simply set the workflow runs filter to that branch and then check the result of the latest run of each workflow of interest. However, that was not possible to do with the release branch since it might be that the workflow was never run in that branch. The status of the latest run of the workflow in the default branch might not match the status for the release branch if the release branch does not contain the full history. For this reason, it will be helpful to trigger all relevant workflows on the creation of a release branch. This will ensure that each of those workflows will always have at least one run in the release branch. Subsequent commits pushed to the branch can run based on their usual trigger filters and the status of the latest run of each workflow in the branch will provide an accurate indication of the state of that branch. Branches are created for purposes other than releases, most notably feature branches to stage work for a pull request. Due to the comprehensive nature of this project's CI system, it would not be convenient or efficient to fully run all CI workflows on the creation of every feature branch. Unfortunately, GitHub Actions does not support filters on the `create` event of branch creation like it does for the `push` and `pull_request` events. There is support for a `branches` filter of the `push` event, but that filter is an "AND" to the `paths` filter while this application requires an "OR". For this reason, the workflows must be triggered by the creation of any branch. The unwanted job runs are prevented by adding a `run-determination` job with the branch filter handled by Bash commands. The other jobs of the workflow use this `run-determination` job as a dependency, only running when it indicates they should via a job output. Because this minimal `run-determination` job runs very quickly, it is roughly equivalent to the workflow having been skipped entirely for non-release branch creations.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,9 +1,11 @@
 name: Arduino IDE
 
 on:
+  create:
   push:
     branches:
       - main
+      - '[0-9]+.[0-9]+.x'
     paths-ignore:
       - '.github/**'
       - '!.github/workflows/build.yml'
@@ -34,8 +36,36 @@ env:
   CHANGELOG_ARTIFACTS: changelog
 
 jobs:
+  run-determination:
+    runs-on: ubuntu-latest
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    permissions: {}
+    steps:
+      - name: Determine if the rest of the workflow should run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
+          TAG_REGEX="refs/tags/.*"
+          # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
+          if [[
+            ("${{ github.event_name }}" != "create" ||
+            "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX) &&
+            ! "${{ github.ref }}" =~ $TAG_REGEX
+          ]]; then
+            # Run the other jobs.
+            RESULT="true"
+          else
+            # There is no need to run the other jobs.
+            RESULT="false"
+          fi
+
+          echo "result=$RESULT" >> $GITHUB_OUTPUT
+
   build:
     name: build (${{ matrix.config.os }})
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
     strategy:
       matrix:
         config:
diff --git a/.github/workflows/check-certificates.yml b/.github/workflows/check-certificates.yml
@@ -3,6 +3,7 @@ name: Check Certificates
 
 # See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
 on:
+  create:
   push:
     paths:
       - '.github/workflows/check-certificates.ya?ml'
@@ -20,12 +21,49 @@ env:
   EXPIRATION_WARNING_PERIOD: 30
 
 jobs:
+  run-determination:
+    runs-on: ubuntu-latest
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    steps:
+      - name: Determine if the rest of the workflow should run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
+          REPO_SLUG="arduino/arduino-ide"
+          if [[
+            (
+              # Only run on branch creation when it is a release branch.
+              # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
+              "${{ github.event_name }}" != "create" ||
+              "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
+            ) &&
+            (
+              # Only run when the workflow will have access to the certificate secrets.
+              # This could be done via a GitHub Actions workflow conditional, but makes more sense to do it here as well.
+              (
+                "${{ github.event_name }}" != "pull_request" &&
+                "${{ github.repository }}" == "$REPO_SLUG"
+              ) ||
+              (
+                "${{ github.event_name }}" == "pull_request" &&
+                "${{ github.event.pull_request.head.repo.full_name }}" == "$REPO_SLUG"
+              )
+            )
+          ]]; then
+            # Run the other jobs.
+            RESULT="true"
+          else
+            # There is no need to run the other jobs.
+            RESULT="false"
+          fi
+
+          echo "result=$RESULT" >> $GITHUB_OUTPUT
+
   check-certificates:
     name: ${{ matrix.certificate.identifier }}
-    # Only run when the workflow will have access to the certificate secrets.
-    if: >
-      (github.event_name != 'pull_request' && github.repository == 'arduino/arduino-ide') ||
-      (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == 'arduino/arduino-ide')
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
diff --git a/.github/workflows/check-i18n-task.yml b/.github/workflows/check-i18n-task.yml
@@ -6,6 +6,7 @@ env:
 
 # See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
 on:
+  create:
   push:
     paths:
       - '.github/workflows/check-i18n-task.ya?ml'
@@ -22,7 +23,35 @@ on:
   repository_dispatch:
 
 jobs:
+  run-determination:
+    runs-on: ubuntu-latest
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    permissions: {}
+    steps:
+      - name: Determine if the rest of the workflow should run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
+          TAG_REGEX="refs/tags/.*"
+          # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
+          if [[
+            ("${{ github.event_name }}" != "create" ||
+            "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX) &&
+            ! "${{ github.ref }}" =~ $TAG_REGEX
+          ]]; then
+            # Run the other jobs.
+            RESULT="true"
+          else
+            # There is no need to run the other jobs.
+            RESULT="false"
+          fi
+
+          echo "result=$RESULT" >> $GITHUB_OUTPUT
+
   check:
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
     runs-on: ubuntu-latest
 
     steps:
diff --git a/docs/internal/release-procedure.md b/docs/internal/release-procedure.md
@@ -1,5 +1,7 @@
 # Release Procedure
 
+The ["trunk-based" development strategy](https://trunkbaseddevelopment.com/) is used for releases of Arduino IDE. A branch named `<major>.<minor>.x` (where `<major>.<minor>` is the major and minor version numbers), is created for each minor version series. Release tags (both pre-release and production) are created from these branches. This allows a release to be created from a select subset of the commits in the `main` branch, [cherry-picked](https://git-scm.com/docs/git-cherry-pick) to the release branch.
+
 ## Steps
 
 The following are the steps to follow to make a release of Arduino IDE:
@@ -39,28 +41,60 @@ 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`.
 - If this is considered a major release (breaking changes to the "API"), the `version` values must be changed to `3.0.0`.
 
-### 4. 🚢 Create the release on GitHub
+### 4. 🍒 Prepare release branch
+
+#### Create
+
+A new release branch must be created on every minor version bump. For example, if you are making the `2.2.0` release, then it is necessary to create a branch named `2.2.x`. That branch will be used for all subsequent releases in the `2.2` minor version series (e.g., `2.2.1`, `2.2.2`).
+
+#### Update
+
+Push all commits that are to be included in the release to the release branch. This can be a [cherry-picked](https://git-scm.com/docs/git-cherry-pick) subset of the commits from the `main` branch if not all the work from `main` is ready for release.
+
+### 5. ✅ Validate release
+
+#### Evaluate CI status
+
+The checks run by the continuous integration system might provide an indication of a problem that should block the release. Since the code in the release branch doesn't necessarily match to that of the `main` branch, it is essential to check the status of the release branch even when everything is passing in the `main` branch.
+
+1. Open the following URL in your browser:<br />
+   https://github.com/arduino/arduino-ide/actions
+1. Type `branch:<release branch>` (where `<release branch>` is the name of the release branch for this release) in the "**Filter workflow runs**" field of the "**Actions**" page.
+1. Press the <kbd>**Enter**</kbd> key.
+1. Wait for all in progress workflow runs to finish.
+1. Click on the first workflow name on the list at the left side of the page.
+1. Check the status of the latest run. If it was not successful, investigate the cause and determine if it is of significance to the release.
+1. Repeat the above steps for each of the listed workflows.
+
+#### Beta testing
+
+The "**Arduino IDE**" workflow run that was triggered by the branch creation will contain artifacts that can be used for beta testing.
+
+[More information about beta testing](../contributor-guide/beta-testing.md)
+
+### 6. 🚢 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.
 
-```text
-git checkout main
-git pull
-git tag -a <YOUR_VERSION> -m "<YOUR_VERSION>"
-git push origin <YOUR_VERSION>
-```
+1. Checkout the release branch in the repository.
+1. Run the following commands:
+   ```text
+   git pull
+   git tag -a <YOUR_VERSION> -m "<YOUR_VERSION>"
+   git push origin <YOUR_VERSION>
+   ```
 
 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.
 
-### 5. ⬆️ Bump version metadata of packages
+### 7. ⬆️ 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).
 
-### 6. 📄 Create the changelog
+### 8. 📄 Create the changelog
 
 **Create GitHub issues for the known issues** that we haven't solved in the current release:
 
@@ -79,7 +113,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.
 
-### 7. ✎ Update the "**Software**" Page
+### 9. ✎ 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.
 
@@ -96,7 +130,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
 
-### 8. 😎 Brag about it
+### 10. 😎 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).<br />
