Add major version ref instructions to release documentation

per1234 · web-flow · commit f191944e577a · 2021-05-01T21:31:47.000-07:00
Recommended practice for GitHub Actions (https://help.github.com/en/actions/building-actions/about-actions#versioning-your-action) is to add a ref to the repository for the major version, then update that ref on each release of that major version series. This allows users of the action to configure their workflows to use the latest version of the action that won't introduce breaking changes. Without this ref, the only options are: - pin a fixed ref - this means either frequent maintenance of the workflow to keep it up to date, or more likely using an outdated version of the action. - reference the tip of the default branch, subjecting the workflow to an unstable version of the action which may introduce bugs or breaking changes at any moment Although GitHub recommends using a tag, my understanding is that it's not considered best practices to alter Git tags. For this reason, I prefer using branch instead of a tag. There is no difference between the two as far as the usage of the action in a GitHub Workflow is concerned. The commits would be pushed to the branch on every release. I see GitHub even took the branch approach in one of the official actions: https://github.com/octokit/request-action Another prominent action using this approach: https://github.com/ruby/setup-ruby And our own actions: - https://github.com/arduino/setup-protoc - https://github.com/arduino/arduino-lint-action - https://github.com/arduino/compile-sketches - https://github.com/arduino/report-size-deltas - https://github.com/arduino/create-changelog - https://github.com/arduino/cpp-test-action
diff --git a/README.md b/README.md
@@ -59,7 +59,13 @@ See the [official Github documentation][pat-docs] to know more about Personal Ac
 3. `npm run test` to see everything works as expected.
 4. `npm run pack` to package for distribution
 5. `git add src dist` to check in the code that matters.
-6. open a PR and request a review.
+6. If the release will increment the major version, update the action refs in the examples in README.md
+   (e.g., `uses: arduino/setup-arduino-cli@v1` -> `uses: arduino/setup-arduino-cli@v2`).
+7. open a PR and request a review.
+8. After PR is merged, create a release, following the `vX.Y.Z` tag name convention.
+9. After the release, rebase the release branch for that major version (e.g., `v1` branch for the v1.x.x tags) on the
+   tag. If no branch exists for the release's major version, create one.
+
 
 [pat-docs]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
 [example]: https://github.com/arduino/arduino-cli-example/blob/master/.github/workflows/test.yaml
