Add generic release checklist for other projects #20
Conversation
travier
force-pushed
the
generic
branch
2 times, most recently
from
a163e2a to
f871980
Compare
|
Looks like we need a fork in https://github.com/coreosbot-releng for CLHM |
No, the fork will be created automatically. |
travier
force-pushed
the
generic
branch
2 times, most recently
from
7b3840e to
351c1e9
Compare
Checklist for projects that are not compiled code or that don't need additional steps beyond the basics.
Use the generic template.
|
I've rewritten the procedure to use a manual tag + PR workflow analog to other ones but sufficiently different that for now I'd say we should keep copies to make things simpler. |
| @@ -73,8 +73,16 @@ repos: | |||
| crate: zincati | |||
| fedora_package: rust-zincati | |||
|
|
|||
| console-login-helper-messages: | |||
There was a problem hiding this comment.
Let's keep both lists in alphabetical order.
| - [ ] `git clean -fd` | ||
| - [ ] `RELEASE_VER=x.y.z` | ||
| - [ ] `PREVIOUS_RELEASE_VER=x.y.z-1` | ||
| - [ ] `UPSTREAM_REMOTE=origin` |
There was a problem hiding this comment.
Should we add a git pull to make sure we've picked up any remote changes? (The other checklists don't do this either; maybe they should.)
| ``` | ||
| git show "v${RELEASE_VER}" | ||
| git tag --verify "v${RELEASE_VER}" | ||
| ``` |
There was a problem hiding this comment.
I'd be in favor of adding an instruction to open a Git history viewer (I use gitk) and verify that the tag is on the expected commit. Tags can't be moved after they're pushed, so this seems worth checking.
|
|
||
| - open and merge a PR for this release: | ||
| - [ ] `git push --tags ${UPSTREAM_REMOTE} release-${RELEASE_VER}` | ||
| - [ ] open a web browser and create a PR for the branch above |
There was a problem hiding this comment.
What are we PRing here? We've created a branch but not committed anything to it, and we've already pushed the tag so we couldn't change any commits anyway.
| - [ ] write release notes in `docs/release-notes.md`. You can follow the following template: | ||
| ``` | ||
| cat <<EOF > release-notes.txt | ||
| This is release ${NEWTAG} of console-login-helper-messages. |
There was a problem hiding this comment.
console-login-helper-messages needs to be templated.
But also, this message is pretty verbose for its content. Is this what we want?
|
|
||
| Thanks to the following contributors for patches during this release: | ||
|
|
||
| $(git shortlog --no-merges --pretty=format:"%h %s" -e ${PREVIOUS_RELEASE_VER}..HEAD) |
There was a problem hiding this comment.
I don't think we should do this. Two reasons:
${PREVIOUS_RELEASE_VER}has to be looked up manually, which is a potential source of errors.- Git logs are developer-facing; changelogs are user-facing. If developers want to know what changed, they can look at Git anyway. Users shouldn't be handed a Git shortlog and told to figure it out themselves. (For an example of how this fails, check out older Afterburn releases.)
Potential alternatives:
- Don't bother with a changelog.
- Open an issue with the changelog text, collect LGTMs, close issue, paste into tag message and GitHub release.
- Maintain a
CHANGELOG.mdordocs/release-notes.mdand use a proper PR flow.docs/probably doesn't make sense for projects that don't have a GitHub Pages site.
I think we should do both but I'm not sure how well it would works out in practice:
But maybe that's too cumbersome as we need to re-update the tag every time we address review comments. |
|
If we want to include release notes in the repo itself, we shouldn't create the tag until after the PR merges. Stale tags are dangerous: they could be pushed accidentally, at which point they're immutable. (And in that case, I'd favor leaving the release notes out of the tag message, for simplicity. That's what we do everywhere else.) |
|
Just my 2c: I love the idea of a changelog.md but isn't it going to be a conflict-fest? I see discussion related to this in PrefectHQ/prefect#2311
The distinction between these two shrinks significantly (imo to nearly nil) for projects where all users are developers - i.e. libraries such as https://github.com/coreos/cap-std-ext/ |
Unknown, but I suspect not. Our rate of change in upstream projects isn't that high, and I suspect that's especially true in projects that will use this particular checklist. In Afterburn/Butane/coreos-installer/Ignition we've started updating the changelog in each PR and it's seemed okay so far. And also, IMO changelogs should be sorted in order of significance, not in chronological order, which helps cut down on conflicts.
I don't agree. Developers using an API need to know about breaking changes, new features, and bug fixes, the same as in user-facing projects. They shouldn't need to sort through random refactor commits, dependency updates, and CI improvements to figure out which changes will affect them. |
Yeah the common pattern for that is to tag the commits |
|
To be clear, though, filtering isn't enough. A single semantic change might be spread across many commits, and their commit logs will have been written to be useful to developers of the project, not to outside users. I've been writing release notes for a long time, and I don't think there's any automated substitute for the perspective shift needed when explaining code changes to the userbase. |
Also, this checklist wouldn't necessarily require the changelog to be updated in each PR. It could be written entirely at release time. |
Add generic release checklist for other projects
Checklist for projects that are not compiled code or that don't need
additional steps beyond the basics.
config: Add console-login-helper-messages
Use the generic template.