doc: commit header convention for documentation changes

[DanielSidhion]

Description of changes

I just made a PR for documentation changes and didn't find the convention for commit messages in this case. I did a quick search through open PRs and seems like most people use doc: <summary> for documentation PRs, so I'm going with that, mostly because it matches the doc/ directory for documentation.

If this isn't the actual convention, hopefully this PR generates enough discussion to figure out what the convention is (or should be).

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 23.11 Release Notes (or backporting 23.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

[fricklerhandwerk]

Is there a need for formatted commit headers on documentation? I understand the one about packages and modules because it helps a bit with dissecting. But what else exactly would we need commit headers for? To filter for reviews we have labels, some of which are automated. So far I see no benefit but only additional overhead and some potential for nit-picky comments.

That said, I'm not against the direction of the change if others want it, as long as the rationale is clarified and encoded in the commit message. I'd just suggest refactoring the template here because it's getting messy and hard to decode.

[infinisil]

The commit subject convention should really be documented in the more specific files pkgs/README.md, nixos/README.md, etc. instead

[DanielSidhion]

The rationale for this change is to reassure newer contributors that the process for docs contributions is roughly the same as any other contribution. There's quite an extensive guide on making (and reviewing) code contributions, but compared to the amount of information on making docs contributions, one wonders whether the process is similar at all. I only proceeded with making a PR for docs changes because I was encouraged by other members of the community.

Having a header for docs changes listed in the convention would've helped reassure me that yes, I can go ahead and make a PR. These details matter.

After I made my PR, I learned that sometimes it may be useful to ping the documentation team on a PR as well to help with feedback, so I'm leaning towards:

• adding info on the commit header to doc/README.md,
• adding info on pinging the documentation team if their feedback is needed during the review of a PR,
• and adding a small section Contributing to documentation in CONTRIBUTING.md pointing to doc/README.md.

What do you folks think?

[infinisil]

Sounds good to me! Regarding the section on contributing to docs, I think it would be great to extend the overview section for that. It already links to the doc/README.md, but it could be improved.

[DanielSidhion]

I separated the conventions for each particular area and added a sentence to ping the documentation team during a PR review if needed. Couldn't find a way to improve the overview section, but the commit conventions section also links to specific parts of each README.md, so I think this is an improvement.

[infinisil]

This is lovely, thanks! Just a minor nit :)