add note on versioning approach to changelog #2044
Conversation
CHANGELOG.md
Outdated
| @@ -2,6 +2,8 @@ | |||
|
|
|||
| See the [releases page](https://github.com/github/codeql-action/releases) for the relevant changes to the CodeQL CLI and language packs. | |||
|
|
|||
| Note that for the CodeQL Action we use the major version number to mark a change in the node version used, while the minor & patch numbers indicate releases that support the same features across node versions. For example `3.22.11` is the first `v3` release and is functionally identical to `2.22.11`, which was released while we continue to support `v2`. This approach ensures an easy way to track exactly which features are included in different versions. | |||
There was a problem hiding this comment.
Can you mention that there is feature parity between v2 and v3? They only difference is that v2 runs on node 16 and v3 node 20. This is implied, but not stated outright.
Also, this paragraph implies that the only reason we bump major versions is to support a new node version. That happens to be the case for the last two major releases, but may not be so in the future. Maybe you can change the note to
Note that the only difference between v2 and v3 of the CodeQL Action is the node version they support...
(Or something like that.)
There was a problem hiding this comment.
I've pushed another commit, which may or may not reflect an improvement in clarity... 😅
CHANGELOG.md
Outdated
| @@ -2,7 +2,7 @@ | |||
|
|
|||
| See the [releases page](https://github.com/github/codeql-action/releases) for the relevant changes to the CodeQL CLI and language packs. | |||
|
|
|||
| Note that for the CodeQL Action we use the major version number to mark a change in the node version used, while the minor & patch numbers indicate releases that support the same features across node versions. For example `3.22.11` is the first `v3` release and is functionally identical to `2.22.11`, which was released while we continue to support `v2`. This approach ensures an easy way to track exactly which features are included in different versions. | |||
| Note that the only difference between `v2` and `v3` of the CodeQL Action is the node version they support, with `v3` running on node 20 while we continue to release `v2` to support running on node 16. This approach ensures an easy way to track exactly which features are included in different versions, indicated by the minor and patch version numbers. | |||
There was a problem hiding this comment.
Thanks, but now it's missing something about 2.x.y and 3.x.y being the same except for node version. It was in the previous attempt and only implied here. 😄
There was a problem hiding this comment.
I have pushed another commit. Review comments containing suggested changes are more than welcome if I'm still not hitting the mark! 😆
There was a problem hiding this comment.
Sorry...reviewing on my phone (power outage), so crafting precise changes it hard.
This PR adds a short explanation of our approach to version numbering at the top of the changelog.
It also ensures any change to the opening text is handled in the mergeback scripting, by anchoring the insertion of the new section to the existing
##heading rather than the previous hardcoded line number.Merge / deployment checklist