diff --git a/Documentation/development/commit-message-format.md b/Documentation/development/commit-message-format.md index c2ad33ecfe..d6ca841d12 100644 --- a/Documentation/development/commit-message-format.md +++ b/Documentation/development/commit-message-format.md @@ -1,20 +1,20 @@ -# Commit Message Format # {#commit_messages} +# Commit Message Format Policy # {#commit_messages} [TOC] -Commit messages should begin with a subject line; try to limit this to no more -than 50-72 characters. The body of the message should be separated from the -subject by a blank line and wrapped at 72 characters. The body of a commit -message should explain what the commit does and why, but do not explain *how* -as the code itself should do that. +Commit messages should begin with a brief subject line. Try to limit this +to no more than 72 characters. The body of the message should be separated +from the subject line by a blank line and wrapped at 72 characters. The body +of a commit message should explain what the commit does and why. Do not +explain *how* the changes work as the code itself should do that. # Linking a commit to a bug report # {#commit_bug_link} If your commit fixes a bug that has been reported in the [Launchpad bug tracker](https://bugs.launchpad.net/kicad/+bugs), end your commit with the following lines to mark it as fixed, where `1234567` represents the actual -bug ID. A bot will automatically set the bug status to "Fix Committed" and link -to the commit once it is merged. +bug ID. A bot will automatically set the bug status to "Fix Committed" and +link to the commit once it is merged. Fixes: lp:1234567 https://bugs.launchpad.net/kicad/+bug/1234567 @@ -23,24 +23,26 @@ There is an [alias](#commit_fixes_alias) to simplify this step. # Changelog tags {#commit_changelog_tag} -To facilitate following the code changes, you should include a changelog tag to -indicate modifications noticable by the users. There are three types of +To facilitate following the code changes, you should include a changelog tag +to indicate modifications noticeable by the users. There are three types of changelog tags: -- `NEW` to denote a new feature +- `ADDED` to denote a new feature - `CHANGED` to indicate a modification of an existing feature - `REMOVED` to inform about removal of an existing feature There is no need to add changelog tags for commits that do not modify the way the users interact with the software, such as code refactoring or a bugfix for -unexpected behavior. The main purpose of the changelog tags is to generate the -release notes and notify the documentation maintainers about changes. Keep that +unexpected behavior. The main purpose of the changelog tags is to generate the +release notes and notify the documentation maintainers about changes. Keep that in mind when deciding whether to add a changelog tag. -When a commit with changelog tags is pushed, the committer should create a new +## Making the Documentation Developers Aware of Changes {#commit_let_doc_team_know} + +When a commit with changelog tag is pushed, the committer should create a new issue in the [documentation repository](http://github.com/KiCad/kicad-doc/issues) to notify the -documentation maintainers. You should include a link to the commit containing +documentation maintainers. You should include a link to the commit containing the reported changes. ## Extracting changelog {#commit_extract_changelog} @@ -48,27 +50,27 @@ the reported changes. Thanks to the changelog tags, it is easy to extract the changelog using git commands: - git log -E --grep="ADD:|NEW:|REMOVE[D]?:|CHANGE[D]?:" --since="1 Jan 2017" - git log -E --grep="ADD:|NEW:|REMOVE[D]?:|CHANGE[D]?:" + git log -E --grep="ADD[ED]?:|REMOVE[D]?:|CHANGE[D]?:" --since="1 Jan 2017" + git log -E --grep="ADD[ED]?:|REMOVE[D]?:|CHANGE[D]?:" -KiCad provides an [alias](#commit_changelog_alias) to shorten the -changelog extraction commands. +KiCad provides an [alias](#commit_changelog_alias) to shorten the changelog +extraction commands. # Example # {#commit_example} Following is an example of a properly formatted commit message: Eeschema: Adding line styling options - - NEW: Adds support in eeschema for changing the default line style, + + ADDED: Add support in Eeschema for changing the default line style, width and color on a case-by-case basis. - + CHANGED: "Wire" lines now optionally include data on the line style, width and color if they differ from the default. - + Fixes: lp:594059 * https://bugs.launchpad.net/kicad/+bug/594059 - + Fixes: lp:1405026 * https://bugs.launchpad.net/kicad/+bug/1405026