Commit-Messages: Updated formatting rules

Author: gtjoseph

docs/Development/Policies-and-Procedures/Commit-Messages.md

@@ -1,12 +1,13 @@
 # Commit Messages
 
-A commit message serves to notify others of the changes made to the Asterisk source code, both in a historical sense and in the present. Commit messages are **incredibly** important to the continued success of the Asterisk project. Developers maintaining the Asterisk project in the future will often only have your commit message to guide them in why a particular change was made. For non-developers, archives containing commit messages may be used when searching for fixes to a particular bug. Be sure that the information contained in your message will help them out.
+This page describes the expected format for commit messages used when submitting code to the Asterisk project. See [Code Contribution](/Development/Policies-and-Procedures/Code-Contribution) for more information about pushing your commit for review.
+
+A commit message serves to notify others of the changes made to the Asterisk source code, both in a historical sense and as part of teh code review process. Commit messages are **incredibly** important to the continued success of the Asterisk project. Developers maintaining the Asterisk project in the future will often only have your commit message to guide them in why a particular change was made. For non-developers, archives containing commit messages may be used when searching for fixes to a particular bug. Be sure that the information contained in your message will help them out.
 
-/// warning | Follow These Guidelines
-Commit messages are part of your code change. Committing code with a poorly written commit message creates a maintenance problem for everyone in the Asterisk project.  
+/// warning | Follow These Rules!
+Commit messages are part of your code change. Committing code with a poorly written commit message creates a maintenance problem for everyone in the Asterisk project.  Pull Requests can and will be rejected if the commit message doesn't follow these rules!
 ///
 
-This page describes the expected format for commit messages used when submitting code to the Asterisk project. See [Code Contribution](/Development/Policies-and-Procedures/Code-Contribution) for more information about pushing your commit for review.
 
 ## Commit Message Body
 
@@ -20,17 +21,17 @@ The following illustrates the basic outline for commit messages:
 <Verbose description of the changes>
 <Empty Line>
 <Special Trailers>
-
 ```
 
 Your summary should, if possible, be preceded by the subsystem(s) affected by the change:
 
 ```
 app_foo: Fix crash caused by invalid widget frobbing.
-
 ```
 
-Most commit history viewers treat the first line of commit messages as the summary for the commit. In addition, the Asterisk project uses many scripts that parse commit messages for a variety of purposes. So, an effort should be made to format our commit messages in this fashion. The verbose description may contain multiple paragraphs, itemized lists, etc. *Always end the first sentence (and any subsequent sentences) with punctuation.*
+GitHub will automatically use the one-line summary as the title for pull requests created from the commit.  The rest of the commit message will then be placed in the first PR comment.
+
+The verbose description may contain multiple paragraphs, itemized lists, etc. *Always end the first sentence (and any subsequent sentences) with punctuation.*
 
 Commit messages should be wrapped at 72 columns.
 
@@ -42,21 +43,25 @@ Since we've moved to a complete GitHub SCM solution, commit messages will automa
 
 ### Special Trailers for Commit Messages
 
-GitHub and our release process support several commit message trailers that are used by the change log generation process.  The trailer name MUST start on a new line, be followed by a colin (`:`) and each should be separated by a blank line.  If specified at all, the trailers listed below MUST be the last items in the commit message.  
+GitHub and the Asterisk release process support several commit message trailers that are used to automatically close related issues and to create the release change logs.  The trailer name MUST start on a new line, be followed by a colon (`:`) and each should be separated by a blank line.  If specified at all, the trailers listed below MUST be the last items in the commit message.
 
 /// warning | Unofficial Trailers
 If you specify any other trailers, including ones that were formerly acceptable, they will become part of the official trailer they follow. So, if you insist on adding trailers like `ASTERISK-nnnnn`, `Signed-Off-By` or `Reported-By` they MUST come BEFORE the first of the official trailers.
 ///
 
 Current official trailers:
 
-* **Resolves**: To reference a GitHub issue, use a  `Resolves: #<issueid>` trailer.  This causes GitHub to automatically close the isse when the PR is merged, and it adds the commit to the list of issues closed in the release change log.
+* **Resolves**: To reference a GitHub issue, use a  `Resolves: #<issueid>` trailer.  This causes GitHub to automatically close the issue when the PR is merged, and it adds the commit to the list of issues closed in the release change log.
 * **Fixes**: Synonym for Resolves.  You can use either.
 * **UpgradeNote**: To make users aware of possible breaking changes on update, use an `UpgradeNote: <text>` trailer.
 * **UserNote**: To make users aware of a new feature or significant fix, use a `UserNote: <text>` trailer.
 
 Any user-affecting change (new feature, change to CLI commands, etc) must be documented with a `UserNote:` trailer.   Any breaking change (change to dialplan application or function arguments, API change, etc.) must be documented with an `UpgradeNote:` trailer.   Those trailers cause special notes to be output in the change log in addition to the full commit message.
 
+/// warning | Updating Commit Messages
+GitHub only looks in the PR comments for the `Resolves` or `Fixes` trailers not the commit message, however the Asterisk release process only looks in the commit message for the trailers so it's important that they match.  Be aware though, if you subsequently force push the commit after the PR is created, GitHub will NOT automatically update the PR title or the description/first comment from the updated commit so if you've added or changed the `Resolves:` or `Fixes:` trailers in the commit message and forced pushed, you MUST manually edit the PR description/first comment or GitHub won't be able to automatically close any related issues.
+///
+
 ## Example complete commit message:
 
 ```