Use one branch for a single task, unless you’re fixing typos or markup on several pages. Long commit histories are hard to manage and sometimes end up stale.
Start a new branch from the last commit on
Make sure to update your local version of
Otherwise, you may have to rebase later.
Name your branch so it’s clear what you’re doing. Examples:
- Most of the time, one-line commit messages are sufficient for documentation changes.
- When you squash commits at merge, the resulting commit message is a sum of all commit messages in the PR. It is advised to include the “resolves” string in the first commit. Otherwise, there’s a risk that this line won’t be included in the merge commit.
- Convey the nature of the change and possibly the reason why it was made.
- Don’t specify the files you’ve changed or the issue you’re working on. The file names can be looked up in the “Files” section of the PR, and the PR description has the issue number(s).
- Try keeping the commit title 50 characters or shorter.
- Use the imperative mood.
- Start with a capital letter, don’t add ending punctuation.
- (Optional) Use the telegraphic style, or “headlinese”, dropping the articles.
git commit -m "Expand section on msgpack"
git commit -m "Add details on IPROTO_BALLOT"
git commit -m "Create new structure"
git commit -m "Improve grammar"
git commit -m "Fix gh-2007, second commit"
git commit -m “Changed the file box_protocol.rst”
git commit -m "added more list items"
Ideally, a PR should have two reviewers: a subject matter expert (SME) and a documentarian. The SME checks the facts, and the documentarian checks the language and style.
If you’re not sure who the SME for an issue is, try the following:
- Check the issue description. The SME is often mentioned there explicitly.
- Note who created the issue and who was involved in the discussion.
Merge when your document is ready and good enough. For external contributors, merging is blocked until a reviewer’s approval.
- Always squash commits.
- Make sure the commit message mentions all relevant issues with “resolves” or “fixes”.
- Make sure you’ve
all participants with