diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -1595,10 +1595,16 @@ |`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. +|`Reported by:` +|The name and e-mail address of the person that reported the issue; for developers, just the username on the FreeBSD cluster. +Typically used when there is no PR, for example if the issue was reported on +a mailing list. + |`Submitted by:` -| +|The name and e-mail address of the person that submitted the fix; for developers, just the username on the FreeBSD cluster. -The name and e-mail address of the person that submitted the fix; for developers, just the username on the FreeBSD cluster. +Typically not used with git; in the src and doc trees submitted patches should +have the author set by using `git commit --author` If the submitter is the maintainer of the port being committed, include "(maintainer)" after the email address. @@ -1607,10 +1613,20 @@ |`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. +|`Tested by:` +|The name and e-mail address of the person or people that tested the change; for developers, just the username on the FreeBSD cluster. + |`Approved by:` a| -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. +The name and e-mail address of the person or people that approved the change; for developers, just the username on the FreeBSD cluster. + +There are several cases where approval is customary: + +* while a new committer is under mentorship +* commits to an area of the tree to which you do not usually commit +* during a relese cycle +* committing to a repo where you do not hold a commit bit (e.g. src committer committing to docs) While under mentorship, get mentor approval before the commit. Enter the mentor's username in this field, and note that they are a mentor: @@ -1629,8 +1645,9 @@ |`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. +|`Fixes:` +|The git short hash as returned by `git rev-parse --short` (or SVN revision +number, for ports) and the title line of a commit that is fixed by this change. |`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. @@ -1641,6 +1658,9 @@ |`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. +|`MFH:` +|A ports quarterly branch name, to request approval for merge. + |`Relnotes:` |If the change is a candidate for inclusion in the release notes for the next release from the branch, set to `yes`. @@ -1650,6 +1670,9 @@ |`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. +|`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. + |`Differential Revision:` |The full URL of the Phabricator review. This line __must be the last line__. For example: `https://reviews.freebsd.org/D1708`. |===