== Commit Rules ==

=== General ===

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.