Skip to content

Add major version ref instructions to release documentation #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 3, 2021
Merged

Add major version ref instructions to release documentation #25

merged 1 commit into from
May 3, 2021

Conversation

per1234
Copy link
Contributor

@per1234 per1234 commented May 2, 2021

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:

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
@per1234 per1234 added topic: documentation Related to documentation for the project type: enhancement Proposed improvement labels May 2, 2021
@per1234 per1234 requested review from silvanocerza, umbynos and rsora May 2, 2021 04:32
@per1234 per1234 merged commit 3582a0e into arduino:master May 3, 2021
@per1234 per1234 self-assigned this Nov 23, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic: documentation Related to documentation for the project type: enhancement Proposed improvement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants