Move from sliding tags to branch based versioning

[ericcornelissen]

Project Initiative

Update the versioning strategy from a sliding tag¹ to a branch-based release strategy. Per the references, updating the commit that a tag points to is not "the git way". Using a branch for a continuously updating point of reference in the repository is more natural, and supported by GitHub Actions.

Options

Sliding v2 branch

Have a branch called v2 that points to some commit on the main branch, as suggested in the changes proposed in [2].

Example, going from:

gitGraph
  commit id: "fa6b1f8"
  commit id: "ca2f706" tag: "v2.0.1"
  commit id: "50860d3"
  commit id: "f164e28"
  commit id: "c2b9047 (v2)" type: HIGHLIGHT tag: "v2.1.0"
  commit id: "a473695"
  commit id: "fa3f790"

Loading

with the v2 branch pointing to c2b9047, to

gitGraph
  commit id: "fa6b1f8"
  commit id: "ca2f706" tag: "v2.0.1"
  commit id: "50860d3"
  commit id: "f164e28"
  commit id: "c2b9047" tag: "v2.1.0"
  commit id: "a473695"
  commit id: "fa3f790 (v2)" type: HIGHLIGHT tag: "v2.1.1"

Loading

with the v2 branch pointing to fa3f790.

Dedicated v2 branch

Have a dedicated v2 branch that main is occasionally merged into to cut a release. This is similar to the main-develop strategy (where develop=main and main=v2).

gitGraph
  commit id: "test" tag: "v2.0.1"
  branch v2
  commit id: "init branch"
  checkout main
  commit id: "feature"
  checkout v2
  merge main tag: "v2.1.0"
  checkout main
  commit id: "bugfix"
  checkout v2
  merge main tag: "v2.1.1"
  checkout main
  commit id: "chore"

Loading

Rename main to v2

Stop using a main branch and just have v2 branch. This would be simple, but means the v2 ref is unstable. Hence, at the very list this would require a breaking change (i.e. jump to v3).

gitGraph
  branch v2
  checkout v2
  commit id: "fa6b1f8"
  commit id: "ca2f706" tag: "v2.0.1"
  commit id: "50860d3"
  commit id: "f164e28"
  commit id: "c2b9047" tag: "v2.1.0"
  commit id: "a473695"

Loading

Others?

Suggestions are welcome (even if this issue has since been closed).

References

1. https://git-scm.com/docs/git-tag#_on_re_tagging
2. Recommend updating branches for major versions and not tags in the versioning docs actions/toolkit#631 (and related)

Footnotes

1. Sliding a tag meaning updating the commit that a tag points to. ↩

[ericcornelissen]

At least initially, this project will go for the "Sliding v2 branch" approach.

Progress

• Update the Release Guidelines (Update release process to be sliding branch based #269)
• Update the Release workflow (Update release process to be sliding branch based #269)
• Update the git refs (for v2)
• Update the git refs (for v1)