[MacPorts] CommitRules modified

[MacPorts]

Page "CommitRules" was changed by raimue
Diff URL: <https://trac.macports.org/wiki/CommitRules?action=diff&version=7>
Revision 7
Comment: Adapt the commit rules for use with Git and GitHub
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: CommitRules
=========================================================================
--- CommitRules (version: 6)
+++ CommitRules (version: 7)
@@ -7,28 +7,44 @@
 1. Reference any tickets that are related to the change, preferably with a [wiki:TracLinks Trac link]
 
 
-=== Using sensible commit messages ===
+=== Using sensible commit messages === #messages
 
-When committing your changes to MacPorts' central port tree using subversion it is good practice to use properly formatted commit messages.
+When publishing your changes in MacPorts' ports tree, it is good practice to use properly formatted commit messages.
 
-Think about others reading the [/timeline timeline]. Here you want to see on first glance which port got modified, therefore the recommended format for commit messages is this:
+Think about others reading the [/timeline timeline] or viewing `git log --oneline`. Here you want to see on first glance which port got modified, therefore the recommended format for commit messages is this:
 {{{
-PORTNAME: COMMENT
+portname: summary, max 50 characters
+
+A longer, optional comment may follow after a blank line, explaining
+all of your changes. Git will not wrap paragraphs automatically, so it
+is generally recommended to wrap long lines at 72 characters, which is
+a limit inherited from email.
 }}}
 Here a reader of MacPorts' timeline can quickly get the most important information, i.e. ''which'' port got changed and ''why''.
 
 A real-life example is:
 {{{
-zmq: Fix build on darwin <= 10, closes #40663
+zmq: fix build on macOS 10.12
+
+This fixes a build failure on macOS 10.12 Sierra by backporting a patch
+from upstream.
+
+Closes https://trac.macports.org/ticket/40663
 }}}
-Note that references to [wiki:Tickets Trac tickets] can be inserted using the '#' as well as references to certain commits of the MacPorts repository by using 'r' (e.g. r111866).
+References to [wiki:Tickets Trac tickets] can only be inserted with the full URL. The '#' syntax is reserved for pull requests on GitHub.
 
 If a change affects multiple ports, list all affected ports. If a change affects a large number of ports, listing their names is not necessary.
 
-=== Correcting mistakes ===
+Further reading explaining these rules:
+  * http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+  * http://chris.beams.io/posts/git-commit/
 
-If you make a mistake in the commit message, our svn repository is configured so that you can edit it after the fact via
+=== Correcting mistakes === #amend
+
+If you have '''already pushed''' the commit to GitHub, the commit message can no longer be changed. You may add a comment on GitHub to the commit to clarify your mistake.
+
+If you have '''not yet pushed''' the commit, and only when you have not yet pushed it, the last commit you made can still be edited with:
 {{{
-svn propedit --revprop svn:log -r XXX
+git commit --amend
 }}}
-(replacing XXX with the revision number).
+Please note again: this will change the hash of the commit. This can only be used on local commits that were not yet pushed to GitHub.
-------8<------8<------8<------8<------8<------8<------8<------8<--------

--
Page URL: <https://trac.macports.org/wiki/CommitRules>
MacPorts <https://www.macports.org/>
Ports system for macOS

This is an automated message. Someone added your email address to be
notified of changes on 'CommitRules' page.
If it was not you, please report to admin at macports.org.