CONTRIBUTING: Package bumps should reference release notes #200922
Conversation
ofborg
bot
added
10.rebuild-darwin: 0
CONTRIBUTING.md
Outdated
| @@ -51,7 +51,7 @@ See the nixpkgs manual for more details on [standard meta-attributes](https://ni | |||
|
|
|||
| In addition to writing properly formatted commit messages, it's important to include relevant information so other developers can later understand *why* a change was made. While this information usually can be found by digging code, mailing list/Discourse archives, pull request discussions or upstream changes, it may require a lot of work. | |||
|
|
|||
| For package version upgrades and such a one-line commit message is usually sufficient. | |||
| For package version upgrades a simple commit message indicating the old and new version with a reference to the release notes or changelog are sufficient. | |||
There was a problem hiding this comment.
It is not quite clear that the headline is a must and the changelog is a should.
There was a problem hiding this comment.
I should probably change that to must be given, if one exists. Thanks for the pointer. 😛
There was a problem hiding this comment.
The meta.changelog could be referenced for such things.
There was a problem hiding this comment.
Yeah, sure. Now only tools like nix-update and nixpkgs-update need to catch up in that regard.
|
Can't we do a bot that fixes those up if a changelog exists? Also people are going to chase me out of town with torches if I request this from them while reviewing. |
|
Well, here's two things in response to that:
|
If we would make the changelog URL static without the version in it, then it would be super easy to get to the changelog regardless if people manually put it into the commit body or used tools that do that. |
There was a problem hiding this comment.
Some suggestions:
- For simple version updates/upgrades, the ones that merely changes version and checksum, a one-line commit and a link to the changelog (when possible - some projects do not have changelog files) should suffice.
- Things that change the whole logic of Nix expression - such like "the build system changed from autotools to meson" - should be included in the commit messages.
Ideally |
This change improves the recommendation for good commit messages to include release notes on package bumps. Including the release notes increases the likelihood that they will be taken into consideration during review. Having them included in the review is important to be able to judge whether changes made during a version bump are sensible, sufficient or complete. The burden of retrieving the release notes for arbitrary package bumps should not rest on the relatively small group of reviewers. Signed-off-by: Martin Weinelt <[email protected]>
mweinelt
force-pushed
the
contributing-pkg-bump-rls-notes
branch
from
21db2bf to
8e4f503
Compare
|
Updated the wording taking some feedback into consideration. PTAL. |
Release notes for package upgrades are immensely helpful in judging whether the changes made to a package during a version bump are sensible, sufficient or complete.
This change clarifies that a good commit message should contain such a reference.
cc Mic92/nix-update#87
Description of changes
Things done
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)nixos/doc/manual/md-to-db.shto update generated release notes