From 890179d06befbed024e3027d91ebe63a1018cfa0 Mon Sep 17 00:00:00 2001 From: Jens Axboe Date: Fri, 12 Nov 2021 10:09:51 -0700 Subject: [PATCH] Add more explanations to the github PR template I don't care about what happens on github, the git tree is what is important in terms of commit messages. Add a section on splitting changes up. Each change should do just one thing. If it does more than one thing, most likely it should be in a separate commit. Signed-off-by: Jens Axboe --- .github/pull_request_template.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5c7e29ce..ae9f4de9 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -31,17 +31,27 @@ notification, use `[GIT PULL]` as a prefix in your PR title. ### Commit message format rules: 1. The first line is title (don't be more than 72 chars if possible). 2. Then an empty line. -3. Then a description (may be omitted for trivial changes). +3. Then a description (may be omitted for truly trivial changes). 4. Then an empty line again (if it has a description). 5. Then a `Signed-off-by` tag with your real name and email. For example: ``` Signed-off-by: Foo Bar ``` -Description should be word-wrapped at 72 chars. Some things should not -be word-wrapped. They may be some kind of quoted text - long compiler -error messages, oops reports, Link, etc. (things that have a certain -specific format). +The description should be word-wrapped at 72 chars. Some things should +not be word-wrapped. They may be some kind of quoted text - long +compiler error messages, oops reports, Link, etc. (things that have a +certain specific format). + +Note that all of this goes in the commit message, not in the pull +request text. The pull request text should introduce what this pull +request does, and each commit message should explain the rationale for +why that particular change was made. The git tree is canonical source +of truth, not github. + +Each patch should do one thing, and one thing only. If you find yourself +writing an explanation for why a patch is fixing multiple issues, that's +a good indication that the change should be split into separate patches. If the commit is a fix for an issue, add a `Fixes` tag with the issue URL.