6. Setup, Conventions, and Traditions
Prev   Next

6. Setup, Conventions, and Traditions

There are a number of things to do as a new developer. The first set of steps is specific to committers only. These steps must be done by a mentor for those who are not committers.

6.1. For New Committers

Those who have been given commit rights to the FreeBSD repositories must follow these steps.

  • Get mentor approval before committing each of these changes!

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

  • 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 5.3.7, “Adding and Removing Files” regarding adding and removing files. Verify that ~/.subversion/config contains the necessary “auto-props” entries from auto-props.txt mentioned there.

  • All src commits should go to FreeBSD-CURRENT first before being merged to FreeBSD-STABLE. The FreeBSD-STABLE branch must maintain ABI and API compatibility with earlier versions of that branch. Do not merge changes that break this compatibility.

Procedure 1. Steps for New Committers

  1. Add an Author Entity

    head/share/xml/authors.ent — Add an author entity. Later steps depend on this entity, and missing this step will cause the doc/ build to fail. This is a relatively easy task, but remains a good first test of version control skills.

  2. Update the List of Developers and Contributors

    head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml — Add an entry to the “Developers” section of the Contributors List. Entries are sorted by last name.

    head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml — Remove the entry from the “Additional Contributors” section. Entries are sorted by last name.

  3. Add a News Item

    doc/head/share/xml/news.xml — Add an entry. Look for the other entries that announce new committers and follow the format. Use the date from the commit bit approval email from .

  4. Add a PGP Key

    doc/head/share/pgpkeys/pgpkeys.ent and doc/head/share/pgpkeys/pgpkeys-developers.xml - Add your PGP or GnuPG key. Those who do not yet have a key should see Section 2.1, “Creating a Key”.

    Dag-Erling C. Smřrgrav has written a shell script (head/share/pgpkeys/addkey.sh) to make this easier. See the README file for more information.

    Use doc/head/share/pgpkeys/checkkey.sh to verify that keys meet minimal best-practices standards.

    After adding and checking a key, add both updated files to source control and then commit them. Entries in this file are sorted by last name.

    Note:

    It is very important to have a current PGP/GnuPG key in the repository. The key may be required for positive identification of a committer. For example, the FreeBSD Administrators might need it for account recovery. A complete keyring of FreeBSD.org users is available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt.

  5. Update Mentor and Mentee Information

    head/share/misc/committers-repository.dot — Add an entry to the current committers section, where repository is doc, ports, or src, depending on the commit privileges granted.

    Add an entry for the each additonal mentor/mentee relationship in the bottom section.

  6. Generate a Kerberos Password

    See Section 3, “Kerberos and LDAP web Password for FreeBSD Cluster” to generate or set a Kerberos for use with other FreeBSD services like the bug tracking database.

  7. Optional: Enable Wiki Account

    FreeBSD Wiki Account — A wiki account allows sharing projects and ideas. Those who do not yet have an account can contact to obtain one.

  8. Optional: Update Wiki Information

    Wiki Information - After gaining access to the wiki, some people add entries to the How We Got Here, Irc Nicks, and Dogs of FreeBSD pages.

  9. Optional: Update Ports with Personal Information

    ports/astro/xearth/files/freebsd.committers.markers and src/usr.bin/calendar/calendars/calendar.freebsd - Some people add entries for themselves to these files to show where they are located or the date of their birthday.

  10. Optional: Prevent Duplicate Mailings

    Subscribers to svn-src-all, svn-ports-all or svn-doc-all might wish to unsubscribe to avoid receiving duplicate copies of commit messages and followups.

6.2. For Everyone

  1. Introduce yourself to the other developers, otherwise no one will have any idea who you are or what you are working on. The introduction need not be a comprehensive biography, just write a paragraph or two about who you are, what you plan to be working on as a developer in FreeBSD, and who will be your mentor. Email this to the FreeBSD developers mailing list and you will be on your way!

  2. 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:

Those who are developers but not committers will not be subscribed to the committers or developers mailing lists. The subscriptions are derived from the access rights.

6.3. Mentors

All new developers have a mentor assigned to them for the first few months. A mentor is responsible for teaching the mentee the rules and conventions of the project and guiding their first steps in the developer community. The mentor is also personally responsible for the mentee's actions during this initial period.

For committers: do not commit anything without first getting mentor approval. Document that approval with an Approved by: line in the commit message.

When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to mentors.

Prev   Next
5. Subversion Primer Home 7. Commit Log Messages

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.