8. Commit Log Messages

8. Commit Log Messages
Prev		Next

This section contains some suggestions and traditions for how commit logs are formatted.

As well as including an informative message with each commit, some additional information may be needed.

This information consists of one or more lines containing the key word or phrase, a colon, tabs for formatting, and then the additional information.

The key words or phrases are:

`PR:`	The problem report (if any) which is affected (typically, by being closed) by this commit. Multiple PRs may be specified on one line, separated by commas or spaces.
`Submitted by:`	The name and e-mail address of the person that submitted the fix; for developers, just the username on the FreeBSD cluster. If the submitter is the maintainer of the port being committed, include "(maintainer)" after the email address. Avoid obfuscating the email address of the submitter as this adds additional work when searching logs.
`Reviewed by:`	The name and e-mail address of the person or people that reviewed the change; for developers, just the username on the FreeBSD cluster. If a patch was submitted to a mailing list for review, and the review was favorable, then just include the list name.
`Approved by:`	The name and e-mail address of the person or people that approved the change; for developers, just the username on the FreeBSD cluster. It is customary to get prior approval for a commit if it is to an area of the tree to which you do not usually commit. In addition, during the run up to a new release all commits must be approved by the release engineering team. While under mentorship, get mentor approval before the commit. Enter the mentor's username in this field, and note that they are a mentor: Approved by: `username-of-mentor (mentor)` If a team approved these commits then include the team name followed by the username of the approver in parentheses. For example: Approved by: `re (username)`
`Obtained from:`	The name of the project (if any) from which the code was obtained. Do not use this line for the name of an individual person.
`Sponsored by:`	Sponsoring organizations for this change, if any. Separate multiple organizations with commas. If only a portion of the work was sponsored, or different amounts of sponsorship were provided to different authors, please give appropriate credit in parentheses after each sponsor name. For example, `Example.com (alice, code refactoring), Wormulon (bob), Momcorp (cindy)` shows that Alice was sponsored by Example.com to do code refactoring, while Wormulon sponsored Bob's work and Momcorp sponsored Cindy's work. Other authors were either not sponsored or chose not to list sponsorship.
`MFC after:`	To receive an e-mail reminder to MFC at a later date, specify the number of days, weeks, or months after which an MFC is planned.
`MFC to:`	If the commit should be merged to a subset of stable branches, specify the branch names.
`MFC with:`	If the commit should be merged together with a previous one in a single MFC commit (for example, where this commit corrects a bug in the previous change), specify the corresponding revision number.
`Relnotes:`	If the change is a candidate for inclusion in the release notes for the next release from the branch, set to `yes`.
`Security:`	If the change is related to a security vulnerability or security exposure, include one or more references or a description of the issue. If possible, include a VuXML URL or a CVE ID.
`Event:`	The description for the event where this commit was made. If this is a recurring event, add the year or even the month to it. For example, this could be `FooBSDcon 2019`. The idea behind this line is to put recognition to conferences, gatherings, and other types of meetups and to show that these are useful to have. Please do not use the `Sponsored by:` line for this as that is meant for organizations sponsoring certain features or developers working on them.
`Differential Revision:`	The full URL of the Phabricator review. This line must be the last line. For example: `https://reviews.freebsd.org/D1708`.

Example 2. Commit Log for a Commit Based on a PR

The commit is based on a patch from a PR submitted by John Smith. The commit message “PR” and “Submitted by” fields are filled..

...

	    PR:                    12345
	    Submitted by:	   John Smith <John.Smith@example.com>

Example 3. Commit Log for a Commit Needing Review

The virtual memory system is being changed. After posting patches to the appropriate mailing list (in this case, freebsd-arch) and the changes have been approved.

...

	    Reviewed by:       -arch

Example 4. Commit Log for a Commit Needing Approval

Commit a port, after working with the listed MAINTAINER, who said to go ahead and commit.

...

	    Approved by:	    abc (maintainer)

Where abc is the account name of the person who approved.

Example 5. Commit Log for a Commit Bringing in Code from OpenBSD

Committing some code based on work done in the OpenBSD project.

...

	    Obtained from:      OpenBSD

Example 6. Commit Log for a Change to FreeBSD-CURRENT with a Planned Commit to FreeBSD-STABLE to Follow at a Later Date.

Committing some code which will be merged from FreeBSD-CURRENT into the FreeBSD-STABLE branch after two weeks.

...

MFC after:      2 weeks

Where 2 is the number of days, weeks, or months after which an MFC is planned. The weeks option may be day, days, week, weeks, month, months.

It is often necessary to combine these.

Consider the situation where a user has submitted a PR containing code from the NetBSD project. Looking at the PR, the developer sees it is not an area of the tree they normally work in, so they have the change reviewed by the arch mailing list. Since the change is complex, the developer opts to MFC after one month to allow adequate testing.

The extra information to include in the commit would look something like

Example 7. Example Combined Commit Log

PR:                 54321
Submitted by:       John Smith <John.Smith@example.com>
Reviewed by:        -arch
Obtained from:      NetBSD
MFC after:          1 month
Relnotes:           yes

Prev		Next
7. Pre-Commit Review	Home	9. Preferred License for New Files