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.
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.
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.
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 last name.
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
<[email protected]>.
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 <[email protected]> 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.
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 <[email protected]> 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.
Update Mentor and Mentee Information
base/head/share/misc/committers-
— Add an entry to the current committers section,
where repository.dotrepository is
doc, ports, or
src, depending on the commit privileges
granted.
Add an entry for each additional mentor/mentee relationship in the bottom section.
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.
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 <[email protected]>
to obtain one.
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.
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.
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.
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!
Log into freefall.FreeBSD.org and
create a
/var/forward/
(where useruser 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.
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.
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.
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 <[email protected]>.
Send questions about this document to <[email protected]>.