[MacPorts] CommitRules modified

Sun Nov 6 04:25:00 CET 2016

Page "CommitRules" was changed by larryv
Diff URL: <https://trac.macports.org/wiki/CommitRules?action=diff&version=10>
Revision 10
Comment: complete rewrite, incorporating "Commit messages" section from WorkingWithGit
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: CommitRules
=========================================================================

--- CommitRules (version: 9)
+++ CommitRules (version: 10)
@@ -1,55 +1,89 @@
-= Commit Rules =
+= Commit Messages =
+
+Commit messages are a form of communication with other developers. As such, they should be understandable and informative, providing context for the changes that have been made. Since we use Git for version control, messages should also adhere to certain formatting conventions that make it easier to work with Git and related tools.
+
+[[PageOutline(2)]]
+
+== Guidelines == #guidelines
+
+1. **Subject.** Summarize your changes in the first line of the commit message. For very straightforward commits, this one line could suffice as the entire message.
+  - **Include the most important information.** Don't assume that readers can see the entire commit message; subjects often appear in isolation (e.g., GitHub history listings, `git log --oneline`, `git shortlog`).
+  - **Be specific.** Avoid vague subjects like "Update to latest version" or "Fix the build". For example, if you are updating a port to a new upstream version, mention the version number.
+  - **List any modified ports first**, followed by a colon (e.g., "autoconf, libtool:"). To save space, you can use glob notation (e.g., "py3*-numpy:", "clang-3.![6-9]:") or describe the ports' commonality (e.g., "boost dependents:").
+  - **Try to use no more than 50–55 characters**, and treat 60 characters as a hard maximum. Feel free to shunt minor changes down to the message body. If you are having serious trouble meeting these limits, consider breaking up the commit into more atomic pieces that are easier to describe.
+1. **Blank line.** Separate the subject from the body with a blank line; otherwise tools that parse Git history will get confused. Plus, it looks better.
+1. **Body.** Use the rest of the commit message to provide context for your changes.
+  - **Say what the commit itself cannot.** What was the previous behavior, and why was it wrong or suboptimal? How does your commit change that, and why did you choose this particular approach? Don't just translate the commit diff into English. (However, some context is understood and need not be pointed out explicitly. For example, we assume that updating a port is desirable. You do not have to describe the deficiencies of the old version and improvements of the new.)
+  - **Use full Trac URLs.** TracLinks do not work on GitHub (obviously), so refer to Trac tickets by URL instead of number (e.g., "!https://trac.macports.org/ticket/12345" instead of "!#12345").
+  - **Use autolinked references** to refer to GitHub resources. The website [https://help.github.com/articles/autolinked-references-and-urls automatically links] "#//n//" to pull requests and [[span(SHA-1, style=white-space: nowrap)]] hashes to commits.
+  - **Wrap body text at 72 characters.** Git does not do this automatically, so hard-wrap the body to prevent text from overflowing standard-width terminal emulators. This also ensures that the output of `git format-patch` adheres to [http://www.openbsd.org/mail.html#Netiquette good email etiquette]. (You can't do much about very long URLs, unfortunately.)
+
+[https://github.com/macports/macports-ports/commit/d9450d6155ebb83fa8789172502bf2ce2740f77e An example]:
+{{{
+mutt: replace w/neomutt to reduce maint. effort
+
+Maintaining all our patches against mutt in the ports tree is considerable
+effort; now that the NeoMutt project does this for us, replace our mutt port
+with neomutt to avoid wasting our time.
+
+Closes: https://trac.macports.org/ticket/52297
+}}}
+
+== Keywords == #keywords
+
+Commit messages can include keywords that trigger certain Trac actions. The keywords are case-insensitive and must be followed by the URL of a Trac ticket.
+- **"References", "refs", "addresses", "re", "see":** A comment is added to the referenced ticket, containing the commit message and a link to the commit.
+  {{{
+  See https://trac.macports.org/ticket/12345.
+  }}}
+  {{{
+  Re: https://trac.macports.org/ticket/98765
+  }}}
+- **"Close", "closed", "closes", "fix", "fixed", "fixes":** Same as above, and the ticket is closed as "fixed". Similar keywords can be used to [https://help.github.com/articles/closing-issues-via-commit-messages automatically close GitHub pull requests].
+  {{{
+  fixes: https://trac.macports.org/ticket/2468
+  }}}
+  {{{
+  Closes https://trac.macports.org/ticket/13579.
+  }}}
+This functionality is provided by Clemens Lang's [https://github.com/neverpanic/trac-configurable-ctu trac-configurable-ctu], an extension of Trac's [https://trac.edgewall.org/wiki/CommitTicketUpdater Commit Ticket Updater].
+
+== Correcting mistakes == #corrections
+
+Unlike Subversion, which stores changeset logs as mutable [http://svnbook.red-bean.com/en/1.7/svn.advanced.props.html properties], Git commit messages are integral parts of [https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#Commit-Objects commit objects], which are immutable. Correcting a commit's message replaces the commit and all its descendants with new commits (because every commit contains the [[span(SHA-1, style=white-space: nowrap)]] hashes of its parents). This may or may not be a problem.
+
+- You can correct any commit you have not pushed to GitHub by [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-the-Last-Commit amending it] or doing an [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages interactive rebase]. It's good practice to review local commits before pushing them.
+- You cannot correct commits that you have already pushed because our important branches [https://help.github.com/articles/about-protected-branches do not permit force-pushing]. (Force-pushing would be required because your modified local history would diverge from the history on GitHub.) You can comment on the commit's GitHub page instead.
+
+If you have a relatively recent Git, you can easily check whether a commit `deadb33f` is already in the history of a remote branch:
+{{{
+#!sh
+$ git fetch origin master
+$ git merge-base --is-ancestor deadb33f origin/master
+}}}
+
+== Configuring text editors == #editors
+
+Git chooses a text editor for composing commit messages from [https://git-scm.com/docs/git-var#_variables the following sources], in this order:
+1. the `GIT_EDITOR` environment variable
+1. the `core.editor` Git configuration variable
+1. the `VISUAL` environment variable
+1. the `EDITOR` environment variable
+1. the compile-time default (usually vi)
+
+It is best to modify your shell startup files to set the `VISUAL` or `EDITOR` environment variables. Git requires no configuration to use them, and they can be used by other programs too.
+
+If for some reason you want to override `VISUAL`/`EDITOR` and use a different editor with Git, you can specify it in `$HOME/.gitconfig`:
+{{{
+$ git config --global core.editor ed
+}}}
 
 {{{
 #!div style="background-color: lightyellow; padding: 0.25em;"
-TODO: This page needs to be merged with WorkingWithGit#commitmessages
+TODO: Add per-editor information.
 }}}
 
-== General ==
+== Further reading == #more
 
-1. Mention the names of the affected ports (or state what they have in common if there are too many to list individually), since this information is not visible in the revision log
-1. Be specific about what changes were made (for example, when updating to a new upstream version, mention the version number) and, if it's not completely obvious, why they were made
-1. Reference any tickets that are related to the change, preferably with a [wiki:TracLinks Trac link]
-
-
-== Using sensible commit messages == #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] 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: 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 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
-}}}
-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.
-
-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/
-
-== 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:
-{{{
-git commit --amend
-}}}
-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.
+- [http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html A Note About Git Commit Messages] by Tim Pope
+- [http://chris.beams.io/posts/git-commit How to Write a Git Commit Message] by Chris Beams
-------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.
