-
-
Notifications
You must be signed in to change notification settings - Fork 14k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: commit header convention for documentation changes #263059
Conversation
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. |
The commit subject convention should really be documented in the more specific files |
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:
What do you folks think? |
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 |
a46de7e
to
d9f298e
Compare
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is lovely, thanks! Just a minor nit :)
d9f298e
to
e93a3d7
Compare
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 thedoc/
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
nix.conf
? (See Nix manual)sandbox = relaxed
sandbox = true
nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD"
. Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/
)