Skip to content

Commit b21b8c0

Browse files
committed
README: Add commentary on branches and tags
1 parent c013389 commit b21b8c0

File tree

1 file changed

+32
-0
lines changed

1 file changed

+32
-0
lines changed

README.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,38 @@ secrets:
105105
maintainer_key: <string>
106106
```
107107

108+
## Versions, branches and tags
109+
110+
This repository uses [semver][] for version numbers.
111+
112+
Tags will only specify version numbers, and should never change. This is
113+
different to the behaviour for many GitHub official actions, which also use
114+
semver, but where the latest release of any given version is specified by a
115+
_moving_ tag, e.g. [actions/checkout@v4][] is a tag pointing to the latest
116+
v4.x.x release of actions/checkout.
117+
118+
Branches are as follows:
119+
120+
- `main` points to the code that's expected to be in the next release.
121+
- `v*` points to the latest release within a major or minor release sequence.
122+
- `maint/v*` points to the next release within a major or minor release
123+
sequence.
124+
- All other branches are for work in development.
125+
126+
The `main`, `v*` and `maint/v*` branches should only move forward; work on
127+
branches in progress may sometimes be rebased or otherwise changed and are not
128+
expected to have a persistent history.
129+
130+
Bug fixes are, where possible, made in a single commit on a branch taken from
131+
the commit that introduced the bug, as suggested in ["git bugfix branches:
132+
choose the root wisely"][gcbenison], and then merged wherever they need
133+
merging. Possibly this is a terrible idea -- it's definitely not one that
134+
seems to have caught on -- but I like it in theory and want to give it a fair
135+
trial.
136+
108137
[reusable workflows]: https://docs.github.com/en/actions/using-workflows/reusing-workflows
109138
[cygport]: https://cygwin.github.io/cygport/
110139
[PV]: https://cygwin.github.io/cygport/syntax_cygpart.html#PV
140+
[semver]: https://semver.org/spec/v2.0.0.html
141+
[actions/checkout@v4]: https://github.com/actions/checkout/tree/v4
142+
[gcbenison]: https://gcbenison.wordpress.com/2012/01/17/git-bugfix-branches-choose-the-root-wisely/

0 commit comments

Comments
 (0)