Skip to content

Commit e8fb018

Browse files
committed
Add major version ref instructions to release documentation
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 (admittedly, I did it): https://github.com/arduino/setup-protoc
1 parent 6e3cdf1 commit e8fb018

File tree

1 file changed

+10
-5
lines changed

1 file changed

+10
-5
lines changed

.github/CONTRIBUTING.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,15 @@ See the [official Github documentation][pat-docs] to learn more about Personal A
1717
## Release
1818

1919
1. `npm install` to add all the dependencies, included development.
20-
2. `npm run build` to build the Action under the `./lib` folder.
21-
3. `npm run test` to see everything works as expected.
22-
4. `npm run pack` to package for distribution
23-
5. `git add src dist` to check in the code that matters.
24-
6. open a PR and request a review.
20+
1. `npm run build` to build the Action under the `./lib` folder.
21+
1. `npm run test` to see everything works as expected.
22+
1. `npm run pack` to package for distribution
23+
1. `git add src dist` to check in the code that matters.
24+
1. If the release will increment the major version, update the action refs in the examples in README.md
25+
(e.g., `uses: arduino/arduino-lint-action@v1` -> `uses: arduino/arduino-lint-action@v2`).
26+
1. open a PR and request a review.
27+
1. After PR is merged, create a release, following the `vX.X.X` tag name convention.
28+
1. After the release, rebase the release branch for that major version (e.g., `v1` branch for the v1.x.x tags) on the
29+
tag. If no branch exists for the release's major version, create one.
2530

2631
[pat-docs]: https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token

0 commit comments

Comments
 (0)