diff --git a/doc/contributing/docs.rst b/doc/contributing/docs.rst index 6ec5f53fd8..0b21879b9e 100644 --- a/doc/contributing/docs.rst +++ b/doc/contributing/docs.rst @@ -20,3 +20,4 @@ The guidelines are a work in progress, and we welcome all contributions. docs/build docs/sphinx-warnings docs/infra + docs/git diff --git a/doc/contributing/docs/git.rst b/doc/contributing/docs/git.rst new file mode 100644 index 0000000000..108a9e375a --- /dev/null +++ b/doc/contributing/docs/git.rst @@ -0,0 +1,97 @@ +Git workflow +============ + +Branching +--------- + +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 ``latest``. +Make sure to update your local version of ``latest`` with ``git pull``. +Otherwise, you may have to rebase later. + +Name your branch so it's clear what you're doing. Examples: + +* ``short-issue-description`` +* ``gh-1234-short-issue-description`` +* ``your-github-handle/short-issue-description`` + +Linking issues and PRs +---------------------- + +When a PR is linked to an issue: + +* You can go from the issue straight to the PR by clicking the link in the right column. +* The issue will be automatically closed when you close the PR. + +Specify the issue(s) you want to close in the description of your PR. GitHub will connect them if you use specific +`keywords `__. +Here are some of them: + +* Closes #1234 +* Resolves #1234 +* Fixes #1234 + +If your PR closes more than one issue, mention each of them: + +.. code-block:: + + Resolves #1300, resolves #1234, resolves tarantool/doc#100 + +Commit messages +--------------- + +* 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. + +Good examples +~~~~~~~~~~~~~ + +* ``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"`` + +Bad examples +~~~~~~~~~~~~ + +* ``git commit -m "Fix gh-2007, second commit"`` +* ``git commit -m “Changed the file box_protocol.rst”`` +* ``git commit -m "added more list items"`` + +Selecting a reviewer +-------------------- + +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. + +Merging +------- + +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 + `attributed `__ + all participants with ``Co-authored-by``.