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.
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
- 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)
portmgr (erwin, pav) core (wilko)
- When referring to a person in a position (e.g. mentor), write his/her name or alias first, then position(s) in parentheses
phk (mentor) John Doe <firstname.lastname@example.org> (maintainer)
- 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")
PR: 12345 Approved by: John Doe <email@example.com> (maintainer) Approved by: phk (maintainer, implicit) Approved by: portmgr (erwin) Approved by: Dow Jones (maintainer timeout, 25 days) Submitted by: Jane Doe <firstname.lastname@example.org>
Approved by: maintainer Approved by: maintainer timeout Approved by: erwin (portmgr)
Reported by: pointyhat via kris Reported by: pointyhat logs Reported by: portsmon Submitted by: Ports Fury
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:
- Update to 1.5  - Replace deprecated variable: INSTALLS_SHLIB  - Use PORTDOCS to simplify pkg-plist  PR: ports/113760  Submitted by: Antoine Brodin <email@example.com> (maintainer)  Approved by: Antoine Brodin <firstname.lastname@example.org> (maintainer) 
Standard text excerpts
- 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