From 202242790764bf38aa4f4598f787175b9cc7e4ef Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 9 Jul 2024 02:37:23 +0100 Subject: [PATCH] CONTRIBUTING.md: Update the 'Git Style Guide' section This makes it reflect current reality. NOTE: This removes the bit about updating the changes.xml file. For me that has been a constant source of problems. Especially when it hasn't been done as a separate commit (makes reverting changes harder due to this file being constantly re-worked). This file is also usually re-worked at release time, with the re-wording and re-ordering of items. In my experience it is much better to leave the updating of this file to release time when you can use 'git shortlog -e ..' as the source for adding entries to the changelog. Signed-off-by: Andrew Clayton --- CONTRIBUTING.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d8bd230d..eeee56cbc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,29 +63,32 @@ request issue first to start a discussion about the feature. ## Git Style Guide -- Keep a clean, concise and meaningful `git commit` history on your branch, - rebasing locally and squashing before submitting a PR +- Create atomic commits. A commit should do just one thing, i.e. you + shouldn't mix refactoring with functional code changes. Do the + refactoring in one or more commits first. -- For any user-visible changes, updates, and bugfixes, add a note to - `docs/changes.xml` under the section for the upcoming release, using - `` for new functionality, `` - for changed behavior, and `` for bug fixes. + Ideally you should rebase locally and force push new commits up. -- In the subject line, use the past tense ("Added feature", not "Add - feature"); also, use past tense to describe past scenarios, and present - tense for current behavior +- In the subject line, use the imperative mood. I.e. write the subject like + you're giving git a command, e.g. "Free memory before exiting". Do not + terminate the subject with a `.` -- Limit the subject line to 67 characters, and the rest of the commit message - to 80 characters +- Try to limit the subject line to around 50 characters, but try not to + exceed 72. -- Use subject line prefixes for commits that affect a specific portion of the - code; examples include "Tests:", "Packages:", or "Docker:", and also - individual languages such as "Java:" or "Ruby:" +- Wrap the body of the commit message after 72 characters. -- Reference issues and PRs liberally after the subject line; if the commit - remedies a GitHub issue, [name - it](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) - accordingly +- Use lowercase subject line prefixes for commits that affect a specific + portion of the code; examples include "tests:", "ci:", or "http:", and + also individual languages such as "python:" or "php:". If multiple areas + are affected you can specify multiple prefixes, e.g. "auto, perl:" -- Don't rely on command-line commit messages with `-m`; use the editor instead +- If the commit fixes an open issue then you can use the "Closes:" + tag/trailer to reference it and have GitHub automatically close it once + it's been merged. E.g.: + + `Closes: https://github.com/nginx/unit/issues/9999` + + That should go at the end of the commit message, separated by a blank line, + along with any other tags.