4. Conventions and Traditions
Prev |  | Next

## 4. Conventions and Traditions

As a new developer there are a number of things you should do first. The first set is specific to committers only. (If you are not a committer, e.g., have GNATS-only access, then your mentor needs to do these things for you.)

### 4.1. Guidelines for Committers

### Note:

The `.ent`, `.xml`, and `.xml` files listed below exist in the FreeBSD Documentation Project SVN repository at `svn.FreeBSD.org/doc/`.

If you have been given commit rights to one or more of the repositories:

- Add your author entity to `head/share/xml/authors.ent`; this should be done first since an omission of this commit will cause the next commits to break the doc/ build.

  This is a relatively easy task, but remains a good first test of your version control skills.

  ### Important:

  New files that do not have the `FreeBSD=%H` `svn:keywords` property will be rejected when attempting to commit them to the repository. Be sure to read Section 3.3.7, “Adding and Removing Files” regarding adding and removing files, in addition to verifying that `~/.subversion/config` contains the necessary "auto-props" entries from `auto-props.txt` mentioned there.

  ### Note:

  Do not forget to get mentor approval for these patches!

- Also add your author entity to `head/share/xml/developers.ent`.

- Add yourself to the “Developers” section of the Contributors List (`head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml`) and remove yourself from the “Additional Contributors” section (`head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml`). Please note that entries are sorted by last name.

- Add an entry for yourself to `head/share/xml/news.xml`. Look for the other entries that look like “A new committer” and follow the format.

- You should add your PGP or GnuPG key to `head/share/pgpkeys` (and if you do not have a key, you should create one). Do not forget to commit the updated `head/share/pgpkeys/pgpkeys.ent` and `head/share/pgpkeys/pgpkeys-developers.xml`. Please note that entries are sorted by last name.

  Dag-Erling Smørgrav `<des@FreeBSD.org>` has written a shell script (`head/share/pgpkeys/addkey.sh`) to make this extremely simple. See the README file for more information.

  ### Note:

  It is important to have an up-to-date PGP/GnuPG key in the Handbook, since the key may be required for positive identification of a committer, e.g., by the FreeBSD Administrators `<admins@FreeBSD.org>` for account recovery. A complete keyring of `FreeBSD.org` users is available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt.

- Add an entry for yourself to `src/share/misc/committers-`repository`.dot`, where repository is either doc, ports or src, depending on the commit privileges you obtained.

- Some people add an entry for themselves to `ports/astro/xearth/files/freebsd.committers.markers`.

- Some people add an entry for themselves to `src/usr.bin/calendar/calendars/calendar.freebsd`.

- If you already have an account at the FreeBSD wiki, make sure your mentor moves you from the Contributors group to the Developers group. Otherwise, consider signing up for an account so you can publish projects and ideas you are working on.

- Once you get access to the wiki, you may add yourself to the How We Got Here and Irc Nicks pages.

- If you subscribe to svn-src-all, svn-ports-all or svn-doc-all, you will probably want to unsubscribe to avoid receiving duplicate copies of commit messages and their followups.

### Note:

All `src` commits should go to FreeBSD-CURRENT first before being merged to FreeBSD-STABLE. No major new features or high-risk modifications should be made to the FreeBSD-STABLE branch.

### 4.2. Guidelines for Everyone

Whether or not you have commit rights:

- Introduce yourself to the other developers, otherwise no one will have any idea who you are or what you are working on. You do not have to write a comprehensive biography, just write a paragraph or two about who you are and what you plan to be working on as a developer in FreeBSD. (You should also mention who your mentor will be). Email this to the FreeBSD developers mailing list and you will be on your way!

- Log into `hub.FreeBSD.org` and create a `/var/forward/`user`` (where `user` is your username) file containing the e-mail address where you want mail addressed to `yourusername`@FreeBSD.org to be forwarded. This includes all of the commit messages as well as any other mail addressed to the FreeBSD committer's mailing list and the FreeBSD developers mailing list. Really large mailboxes which have taken up permanent residence on `hub` often get “accidentally” truncated without warning, so forward it or read it and you will not lose it.

  Due to the severe load dealing with SPAM places on the central mail servers that do the mailing list processing the front-end server does do some basic checks and will drop some messages based on these checks. At the moment proper DNS information for the connecting host is the only check in place but that may change. Some people blame these checks for bouncing valid email. If you want these checks turned off for your email you can place a file named `.spam_lover` in your home directory on `freefall.FreeBSD.org` to disable the checks for your email.

### Note:

If you are a developer but not a committer, you will not be subscribed to the committers or developers mailing lists; the subscriptions are derived from the access rights.

### 4.3. Mentors

All new developers also have a mentor assigned to them for the first few months. Your mentor is responsible for teaching you the rules and conventions of the project and guiding your first steps in the developer community. Your mentor is also personally responsible for your actions during this initial period.

For committers: until your mentor decides (and announces with a forced commit to `access`) that you have learned the ropes and are ready to commit on your own, you should not commit anything without first getting your mentor's review and approval, and you should document that approval with an `Approved by:` line in the commit message.

Prev |  | Next
3. Subversion Primer | Home | 5. Preferred License for New Files

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.