17. Miscellaneous Questions

17. Miscellaneous Questions
Prev

17.1. Why are trivial or cosmetic changes to files on a vendor branch a bad idea?
17.2. How do I add a new file to a branch?
17.3. What “meta” information should I include in a commit message?
17.4. How do I access people.FreeBSD.org to put up personal or project information?
17.5. Where are the mailing list archives stored?
17.6. I would like to mentor a new committer. What process do I need to follow?

17.1.

Why are trivial or cosmetic changes to files on a vendor branch a bad idea?

From now on, every new vendor release of that file will need to have patches merged in by hand.
From now on, every new vendor release of that file will need to have patches verified by hand.
The -j option does not work very well. Ask David O'Brien <obrien@FreeBSD.org> for horror stories.

17.2.

How do I add a new file to a branch?

To add a file onto a branch, simply checkout or update to the branch you want to add to and then add the file using the add operation as you normally would. This works fine for the doc and ports trees. The src tree uses SVN and requires more care because of the mergeinfo properties. See section 1.4.6 of the Subversion Primer for details. Refer to SubversionPrimer/Merging for details on how to perform an MFC.

17.3.

What “meta” information should I include in a commit message?

As well as including an informative message with each commit you may need to include some additional information as well.

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.
`Submitted by:`	The name and e-mail address of the person that submitted the fix; for committers, just the username on the FreeBSD cluster.
`Reviewed by:`	The name and e-mail address of the person or people that reviewed the change; for committers, 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 committers, 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. If these are your first commits then you should have passed them past your mentor first, and you should list your mentor, as in ```username-of-mentor` `(mentor)`''.
`Obtained from:`	The name of the project (if any) from which the code was obtained.
`MFC after:`	If you wish 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.
`Security:`	If the change is related to a security vulnerability or security exposure, include one or more references or a description of the issue.

Example 1. Commit log for a commit based on a PR

You want to commit a change based on a PR submitted by John Smith containing a patch. The end of the commit message should look something like this.

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

Example 2. Commit log for a commit needing review

You want to change the virtual memory system. You have posted patches to the appropriate mailing list (in this case, freebsd-arch) and the changes have been approved.

... Reviewed by: -arch

Example 3. Commit log for a commit needing approval

You want to commit a change to a section of the tree with a MAINTAINER assigned. You have collaborated with the listed MAINTAINER, who has told you to go ahead and commit.

... Approved by: abc

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

Example 4. Commit log for a commit bringing in code from OpenBSD

You want to commit some code based on work done in the OpenBSD project.

... Obtained from: OpenBSD

Example 5. Commit log for a change to FreeBSD-CURRENT with a planned commit to FreeBSD-STABLE to follow at a later date.

You want to commit 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, or may be left off (in which case, days will be assumed).

In some cases you may need to combine some of these.

Consider the situation where a user has submitted a PR containing code from the NetBSD project. You are looking at the PR, but it is not an area of the tree you normally work in, so you have decided to get the change reviewed by the arch mailing list. Since the change is complex, you opt to MFC after one month to allow adequate testing.

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

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

17.4.

How do I access people.FreeBSD.org to put up personal or project information?

people.FreeBSD.org is the same as freefall.FreeBSD.org. Just create a public_html directory. Anything you place in that directory will automatically be visible under http://people.FreeBSD.org/.

17.5.

Where are the mailing list archives stored?

The mailing lists are archived under /g/mail which will show up as /hub/g/mail with pwd(1). This location is accessible from any machine on the FreeBSD cluster.

17.6.

I would like to mentor a new committer. What process do I need to follow?

See the New Account Creation Procedure document on the internal pages.

Prev
16. Perks of the Job	Home