From e93a3d7b586022f900f176cf46e7a3bf211cfaf9 Mon Sep 17 00:00:00 2001 From: DS Date: Mon, 23 Oct 2023 19:51:50 -0700 Subject: [PATCH] doc: separate commit header conventions for each area, info on docs changes. --- CONTRIBUTING.md | 33 ++++++++++----------------------- doc/README.md | 21 +++++++++++++++++++++ lib/README.md | 20 ++++++++++++++++++++ nixos/README.md | 21 +++++++++++++++++++++ pkgs/README.md | 19 +++++++++++++++++++ 5 files changed, 91 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06b9c10dfec6..ed1b04cf5fe5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -322,6 +322,8 @@ All the review template samples provided in this section are generic and meant a To get more information about how to review specific parts of Nixpkgs, refer to the documents linked to in the [overview section][overview]. +If a pull request contains documentation changes that might require feedback from the documentation team, ping @NixOS/documentation-team on the pull request. + If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic. They will give you information about the reviewing process. The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints. Container system, boot system and library changes are some examples of the pull requests fitting this category. @@ -512,34 +514,19 @@ To get a sense for what changes are considered mass rebuilds, see [previously me - If you have commits `pkg-name: oh, forgot to insert whitespace`: squash commits in this case. Use `git rebase -i`. -- Format the commit messages in the following way: +- For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message). - ``` - (pkg-name | nixos/): (from -> to | init at version | refactor | etc) - - (Motivation for change. Link to release notes. Additional information.) - ``` - - For consistency, there should not be a period at the end of the commit message's summary line (the first line of the commit message). - - Examples: - - * nginx: init at 2.0.1 - * firefox: 54.0.1 -> 55.0 - - https://www.mozilla.org/en-US/firefox/55.0/releasenotes/ - * nixos/hydra: add bazBaz option - - Dual baz behavior is needed to do foo. - * nixos/nginx: refactor config generation - - The old config generation system used impure shell scripts and could break in specific circumstances (see #1234). - - When adding yourself as maintainer, in the same pull request, make a separate +- When adding yourself as maintainer in the same pull request, make a separate commit with the message `maintainers: add `. Add the commit before those making changes to the package or module. See [Nixpkgs Maintainers](./maintainers/README.md) for details. +- Make sure you read about any commit conventions specific to the area you're touching. See: + - [Commit conventions](./pkgs/README.md#commit-conventions) for changes to `pkgs`. + - [Commit conventions](./lib/README.md#commit-conventions) for changes to `lib`. + - [Commit conventions](./nixos/README.md#commit-conventions) for changes to `nixos`. + - [Commit conventions](./doc/README.md#commit-conventions) for changes to `doc`, the Nixpkgs manual. + ### Writing good commit messages 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. diff --git a/doc/README.md b/doc/README.md index 3f9aff1a38a6..9dee2d30d730 100644 --- a/doc/README.md +++ b/doc/README.md @@ -114,3 +114,24 @@ pear watermelon : green fruit with red flesh ``` + +## Commit conventions + +- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. + +- If creating a commit purely for documentation changes, format the commit message in the following way: + + ``` + doc: (documentation summary) + + (Motivation for change, relevant links, additional information.) + ``` + + Examples: + + * doc: update the kernel config documentation to use `nix-shell` + * doc: add information about `nix-update-script` + + Closes #216321. + +- If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes. diff --git a/lib/README.md b/lib/README.md index 627086843db7..220940bc2122 100644 --- a/lib/README.md +++ b/lib/README.md @@ -74,3 +74,23 @@ path/tests/prop.sh # Run the lib.fileset tests fileset/tests.sh ``` + +## Commit conventions + +- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. + +- Format the commit messages in the following way: + + ``` + lib.(section): (init | add additional argument | refactor | etc) + + (Motivation for change. Additional information.) + ``` + + Examples: + + * lib.getExe': check arguments + * lib.fileset: Add an additional argument in the design docs + + Closes #264537 + diff --git a/nixos/README.md b/nixos/README.md index b3cd9d234fa6..7f258eb393a6 100644 --- a/nixos/README.md +++ b/nixos/README.md @@ -8,6 +8,27 @@ https://nixos.org/nixos and in the manual in doc/manual. You can add new module to your NixOS configuration file (usually it’s `/etc/nixos/configuration.nix`). And do `sudo nixos-rebuild test -I nixpkgs= --fast`. +## Commit conventions + +- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. + +- Format the commit messages in the following way: + + ``` + nixos/(module): (init module | add setting | refactor | etc) + + (Motivation for change. Link to release notes. Additional information.) + ``` + + Examples: + + * nixos/hydra: add bazBaz option + + Dual baz behavior is needed to do foo. + * nixos/nginx: refactor config generation + + The old config generation system used impure shell scripts and could break in specific circumstances (see #1234). + ## Reviewing contributions When changing the bootloader installation process, extra care must be taken. Grub installations cannot be rolled back, hence changes may break people’s installations forever. For any non-trivial change to the bootloader please file a PR asking for review, especially from \@edolstra. diff --git a/pkgs/README.md b/pkgs/README.md index 642833d968f3..fc33ecea199e 100644 --- a/pkgs/README.md +++ b/pkgs/README.md @@ -114,6 +114,25 @@ Now that this is out of the way. To add a package to Nixpkgs: 7. Optionally commit the new package and open a pull request [to nixpkgs](https://github.com/NixOS/nixpkgs/pulls), or use [the Patches category](https://discourse.nixos.org/t/about-the-patches-category/477) on Discourse for sending a patch without a GitHub account. +## Commit conventions + +- Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. + +- Format the commit messages in the following way: + + ``` + (pkg-name): (from -> to | init at version | refactor | etc) + + (Motivation for change. Link to release notes. Additional information.) + ``` + + Examples: + + * nginx: init at 2.0.1 + * firefox: 54.0.1 -> 55.0 + + https://www.mozilla.org/en-US/firefox/55.0/releasenotes/ + ## Category Hierarchy [categories]: #category-hierarchy