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+ssh://repo.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 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

    doc/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

    doc/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.

    doc/head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml — Remove the entry from the “Additional Contributors” section. Entries are sorted by first 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 Smřrgrav has written a shell script (doc/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 https://www.FreeBSD.org/doc/pgpkeyring.txt.

  5. Update Mentor and Mentee Information

    base/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 each additional 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 follow instructions on the AboutWiki Page to obtain one. Contact if you need help with your Wiki account.

  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 freefall.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 freefall may get truncated without warning if space needs to be freed, so forward it or save it elsewhere.

    Note:

    If your e-mail system uses SPF with strict rules, you should whitelist mx2.FreeBSD.org from SPF checks.

    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. To have these checks turned off for your email, create a file named ~/.spam_lover on freefall.FreeBSD.org.

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.2.1. SMTP Access Setup

For those willing to send e-mail messages through the FreeBSD.org infrastructure, follow the instructions below:

  1. Point your mail client at smtp.FreeBSD.org:587.

  2. Enable STARTTLS.

  3. Ensure your From: address is set to yourusername@FreeBSD.org.

  4. For authentication, you can use your FreeBSD Kerberos username and password (see Section 3, “Kerberos and LDAP web Password for FreeBSD Cluster”). The yourusername/mail principal is preferred, as it is only valid for authenticating to mail resources.

    Note:

    Do not include @FreeBSD.org when entering in your username.

Additional Notes:

  • Will only accept mail from yourusername@FreeBSD.org. If you are authenticated as one user, you are not permitted to send mail from another.

  • A header will be appended with the SASL username: (Authenticated sender: username).

  • Host has various rate limits in place to cut down on brute force attempts.

6.2.1.1. Using a Local MTA to Forward Emails to the FreeBSD.org SMTP Service

It is also possible to use a local MTA to forward locally sent emails to the FreeBSD.org SMTP servers.

Example 1. Using Postfix

To tell a local Postfix instance that anything from yourusername@FreeBSD.org should be forwarded to the FreeBSD.org servers, add this to your main.cf:

sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous
smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd
smtp_use_tls = yes

Create /usr/local/etc/postfix/relayhost_maps with the following content:

yourusername@FreeBSD.org  [smtp.freebsd.org]:587

Create /usr/local/etc/postfix/sasl_passwd with the following content:

[smtp.freebsd.org]:587          yourusername:yourpassword

If the email server is used by other people, you may want to prevent them from sending e-mails from your address. To achieve this, add this to your main.cf:

smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps
smtpd_sender_restrictions = reject_known_sender_login_mismatch

Create /usr/local/etc/postfix/sender_login_maps with the following content:

yourusername@FreeBSD.org yourlocalusername

Where yourlocalusername is the SASL username used to connect to the local instance of Postfix.


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 conf/mentors. This file is in the svnadmin branch of each repository:

srcbase/svnadmin/conf/mentors
docdoc/svnadmin/conf/mentors
portsports/svnadmin/conf/mentors

New committers should aim to complete enough commits that their mentor is comfortable releasing them from mentorship within the first year. If they are still under mentorship, the appropriate management body (core, doceng, or portmgr) should attempt to ensure that there are no barriers preventing completion. If the committer is unable to satisfy their mentor of readiness by a year and a half their commit bit may be converted to project membership.

Prev   Next
5. Subversion Primer Home 7. Pre-Commit Review

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/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>.