===== Commit Message Format =====
**This page is not authoritative. It is rather a collection of reasonable suggestions.** Feel free to contribute to this page.

There's little technical merit to a standardized commit log format, except for much easier grepping. What we should value here is tradition.
==== Overview ====

<code>
Summary, ~50 characters, no trailing punctuation

This, that. A blank line between the summary line, and this first 
piece of free-form text. Hard wrap at 72 characters.

The other. Again, 72 characters. A blank line between this final 
piece of free-form text, and the colon-separated fields. 

First field:  value
Second field: value
</code>

==== General points ====
  * Don't forget a blank line between text and fields
  * Start lines with a hyphen and a space where appropriate
  * When referring to administrative bodies (e.g. core), write its name first, then alias(es) of the relevant representative(s)

<code>
portmgr (erwin, pav)
core (wilko)
</code>

  * When referring to a person in a position (e.g. mentor), write his/her name or alias first, then position(s) in parentheses

<code>
phk (mentor)
John Doe <a@b.c> (maintainer)
</code>

  * Give proper credit
  * Obfuscate e-mail addresses at will
  * If committer==submitter, the "Submitted by" field may be omitted
  * Don't use pronouns in field values
  * Use a spell-checker
  * Limit characters to US-ASCII
  * Use present tense
  * Use RFC2822 name/e-mail format where appropriate. In particular, don't forget a space between name and opening angle bracket.
  * Specify category of PR's, e.g. src/56789
  * Use proper capitalization. In particular, start sentences with capital letters.
  * Use %%FreeBSD%% aliases instead of names whenever possible
  * Use lowercased make variable names when there is no ambiguity (e.g. "portrevision")
==== Do ====

<code>
PR:           12345
Approved by:  John Doe <john@doe.org> (maintainer)
Approved by:  phk (maintainer, implicit)
Approved by:  portmgr (erwin)
Approved by:  Dow Jones (maintainer timeout, 25 days)
Submitted by: Jane Doe <jane@doe.org>
</code>

==== Don't ====

<code>
Approved by:  maintainer
Approved by:  maintainer timeout
Approved by:  erwin (portmgr)
</code>

==== Special ====

<code>
Reported by:  pointyhat via kris
Reported by:  pointyhat logs
Reported by:  portsmon
Submitted by: Ports Fury
</code>

==== Case studies ====

^ jack wrote ^ commit log ^
| Maybe we should tweak abc | Suggested by: jack |
| Please tweak abc | Requested by: jack |
| Abc doesn't work, fix it! | Reported by: jack |
| Here's a patch | Submitted by: jack |

  * A maintainer sends a PR. You want to commit it with additional changes. The maintainer approves them:

<code>
- Update to 1.5 [1]
- Replace deprecated variable: INSTALLS_SHLIB [2]
- Use PORTDOCS to simplify pkg-plist [2]

PR:            ports/113760 [1]
Submitted by:  Antoine Brodin <brodin@leposte.net> (maintainer) [1]
Approved by:   Antoine Brodin <brodin@leposte.net> (maintainer) [2]
</code>

==== Standard text excerpts ====

<code>
- Update to 1.2.3
- Take maintainership
- Pass maintainership to submitter
- Drop maintainership
Add port foo/bar: <pkg-descr follows>
- Connect foo/bar to the build
- Bump portrevision
- Fix plist
- Add rc script
</code>

----

{{tag>HowTo}}
{{tag>Stale}}