svn commit: r45109 - head/en_US.ISO8859-1/articles/committers-guide
Warren Block
wblock at FreeBSD.org
Tue Jun 24 13:20:27 UTC 2014
Author: wblock
Date: Tue Jun 24 13:20:27 2014
New Revision: 45109
URL: http://svnweb.freebsd.org/changeset/doc/45109
Log:
Clarify and organize the steps for new committers.
Modified:
head/en_US.ISO8859-1/articles/committers-guide/article.xml
Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/committers-guide/article.xml Tue Jun 24 11:24:19 2014 (r45108)
+++ head/en_US.ISO8859-1/articles/committers-guide/article.xml Tue Jun 24 13:20:27 2014 (r45109)
@@ -205,10 +205,17 @@
<sect2 xml:id="pgpkeys-creating">
<title>Creating a Key</title>
- <para>If you do not yet have an Open<acronym>PGP</acronym> key,
- or your key does not meet &os; security requirements, here we
+ <para>Existing keys can be used, but should be checked with
+ <filename>doc/head/share/pgpkeys/checkkey.sh</filename>
+ first.</para>
+
+ <para>For those who do not yet have an Open<acronym>PGP</acronym> key,
+ or need a new key to meet &os; security requirements, here we
show how to generate one.</para>
+ <procedure xml:id="pgpkeys-create-steps">
+
+ <step>
<para>Install
<filename role="package">security/gnupg</filename>. Enter
these lines in <filename>~/.gnupg/gpg.conf</filename> to set
@@ -223,7 +230,9 @@ verify-options show-uid-validity
list-options show-uid-validity
sig-notation issuer-fpr at notations.openpgp.fifthhorseman.net=%g
cert-digest-algo SHA512</programlisting>
+ </step>
+ <step>
<para>Generate a key:</para>
<screen>&prompt.user; <userinput>gpg --gen-key</userinput>
@@ -294,6 +303,8 @@ You need a Passphrase to protect your se
xlink:href="http://www.iusmentis.com/security/passphrasefaq/"></link>,
<link xlink:href="http://xkcd.com/936/"></link>, <link
xlink:href=""></link>.</para>
+ </step>
+ </procedure>
<para>Protect your private key and passphrase. If either the
private key or passphrase may have been compromised or
@@ -301,7 +312,7 @@ You need a Passphrase to protect your se
<email>accounts at FreeBSD.org</email> and revoke the key.</para>
<para>Committing the new key is shown in
- <xref linkend="commit-list"/>.</para>
+ <xref linkend="commit-steps"/>.</para>
</sect2>
</sect1>
@@ -312,12 +323,12 @@ You need a Passphrase to protect your se
password. In the &os; cluster, LDAP is proxying to Kerberos, so
this also serves as the LDAP web password.</para>
- <para>To reset your Kerberos password in the &os; cluster using a
+ <para>To reset a Kerberos password in the &os; cluster using a
random password generator:</para>
<screen>&prompt.user; <userinput>ssh kpasswd.freebsd.org</userinput></screen>
- <para>Alternatively, you can set your Kerberos password manually
+ <para>A Kerberos password can also be set manually
by logging into <systemitem
class="fqdomainname">freefall.FreeBSD.org</systemitem> and
running:</para>
@@ -1531,11 +1542,11 @@ $target - head/$source:$P,$Q,$R</screen>
<title>Practical Example</title>
<para>As a practical example, consider the following
- scenario: The changes to <filename>netmap.4</filename>
- in r238987 is to be merged from CURRENT to 9-STABLE.
+ scenario. The changes to <filename>netmap.4</filename>
+ in r238987 are to be merged from CURRENT to 9-STABLE.
The file resides in
- <filename>head/share/man/man4</filename> and according
- to <xref linkend="svn-advanced-use-merging"/> this is
+ <filename>head/share/man/man4</filename>. According
+ to <xref linkend="svn-advanced-use-merging"/>, this is
also where to do the merge. Note that in this example
all paths are relative to the top of the svn repository.
For more information on the directory layout, see <xref
@@ -2175,140 +2186,165 @@ ControlPersist yes</screen>
</sect1>
<sect1 xml:id="conventions">
- <title>Conventions and Traditions</title>
+ <title>Setup, Conventions, and Traditions</title>
<para>There are a number of things to do as a new developer.
- The first set is specific to committers only. (If
- you are not a committer, e.g., have GNATS-only access, then your
- mentor must do these things.)</para>
+ The first set of steps is specific to committers only. These
+ steps must be done by a mentor for those who are not
+ committers.</para>
<sect2 xml:id="conventions-committers">
- <title>Guidelines for Committers</title>
+ <title>For New Committers</title>
- <note>
- <para>The <literal>.ent</literal>
- and <literal>.xml</literal> files listed below exist in the
- &os; Documentation Project SVN repository at <systemitem
- class="fqdomainname">svn.FreeBSD.org/doc/</systemitem>.</para>
- </note>
-
- <para>If you have been given commit rights to one or more of the
- repositories:</para>
-
- <itemizedlist xml:id="commit-list">
- <title>Steps for New Committers</title>
+ <para>Those who have been given commit rights to the &os;
+ repositories must follow these steps.</para>
+ <itemizedlist xml:id="commit-notes">
<listitem>
- <para>Add your author entity to
- <filename>head/share/xml/authors.ent</filename>; this
- should be done first since an omission of this commit will
- cause the next commits to break the doc/ build.</para>
-
- <para>This is a relatively easy task, but remains a good
- first test of your version control skills.</para>
-
- <important>
- <para>New files that do not have the
- <literal>FreeBSD=%H</literal>
- <command>svn:keywords</command> property will be
- rejected when attempting to commit them to the
- repository. Be sure to read
- <xref linkend="svn-daily-use-adding-and-removing"/>
- regarding adding and removing files, in addition to
- verifying that <filename>~/.subversion/config</filename>
- contains the necessary "auto-props" entries
- from <filename>auto-props.txt</filename> mentioned
- there.</para>
- </important>
-
- <note>
- <para>Do not forget to get mentor approval for these
- patches!</para>
- </note>
+ <para>Get mentor approval before committing each of these
+ changes!</para>
</listitem>
<listitem>
- <para>Add yourself to the <quote>Developers</quote> section
- of the <link
- xlink:href="&url.articles.contributors;/index.html">Contributors
- List</link>
- (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>)
- and remove yourself from the
- <quote>Additional Contributors</quote> section
- (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>).
- Please note that entries are sorted by last name.</para>
+ <para>The <filename>.ent</filename> and
+ <filename>.xml</filename> files mentioned below exist in the
+ &os; Documentation Project SVN repository at <link
+ xlink:href="svn.FreeBSD.org/doc/"><literal>svn.FreeBSD.org/doc/</literal></link>.</para>
</listitem>
<listitem>
- <para>Add an entry for yourself to
- <filename>head/share/xml/news.xml</filename>. Look for
- the other entries that look like
- <quote>A new committer</quote> and follow the
- format.</para>
+ <para>New files that do not have the
+ <literal>FreeBSD=%H</literal>
+ <command>svn:keywords</command> property will be rejected
+ when attempting to commit them to the repository. Be sure
+ to read
+ <xref linkend="svn-daily-use-adding-and-removing"/>
+ regarding adding and removing files.
+ Verify that <filename>~/.subversion/config</filename>
+ contains the necessary <quote>auto-props</quote> entries from
+ <filename>auto-props.txt</filename> mentioned
+ there.</para>
</listitem>
<listitem>
- <para>Add your PGP or GnuPG key to
- <filename>head/share/pgpkeys</filename>. See <xref linkend="pgpkeys-creating"/>
- if you do not yet have a key. Do not forget to
- commit the updated
- <filename>head/share/pgpkeys/pgpkeys.ent</filename> and
- <filename>head/share/pgpkeys/pgpkeys-developers.xml</filename>.
- Please note that entries are sorted by last name.</para>
+ <para>All <filename>src</filename> commits should go to
+ &os.current; first before being merged to &os.stable;.
+ The &os.stable; branch must maintain <acronym>ABI</acronym>
+ and <acronym>API</acronym> compatibility with earlier
+ versions of that branch. Do not merge changes that break
+ this compatibility.</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure xml:id="commit-steps">
+ <title>Steps for New Committers</title>
+
+ <step>
+ <title>Add an Author Entity</title>
+
+ <para><filename>head/share/xml/authors.ent</filename> —
+ Add an author entity. Later steps depend
+ on this entity, and missing this step will
+ cause the
+ <filename>doc/</filename> build to fail. This is a relatively easy task, but remains a good
+ first test of version control skills.</para>
+ </step>
+
+ <step>
+ <title>Update the List of Developers and Contributors</title>
+
+ <para><filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename> —
+ Add an entry to the <quote>Developers</quote> section
+ of the <link
+ xlink:href="&url.articles.contributors;/staff-committers.html">Contributors
+ List</link>. Entries are sorted by last name.</para>
+ <para><filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename> —
+ Remove the entry from the
+ <quote>Additional Contributors</quote> section.
+ Entries are sorted by last name.</para>
+ </step>
+
+ <step>
+ <title>Add a News Item</title>
+ <para><filename>doc/head/share/xml/news.xml</filename> —
+ 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>core at FreeBSD.org</email>.</para>
+ </step>
+
+ <step>
+ <title>Add a <acronym>PGP</acronym> Key</title>
+ <para><filename>doc/head/share/pgpkeys/pgpkeys.ent</filename> and
+ <filename>doc/head/share/pgpkeys/pgpkeys-developers.xml</filename> -
+ Add your <acronym>PGP</acronym> or Gnu<acronym>PG</acronym> key.
+ Those who do not yet have a key should see <xref linkend="pgpkeys-creating"/>.</para>
<para>&a.des.email; has written a shell script
(<filename>head/share/pgpkeys/addkey.sh</filename>) to
- make this extremely simple. See the <link
+ make this easier. See the <link
xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link>
file for more information.</para>
+ <para>Use
+ <filename>doc/head/share/pgpkeys/checkkey.sh</filename> to
+ verify that keys meet minimal best-practices
+ standards.</para>
+
+ <para>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.</para>
+
<note>
- <para>It is important to have an up-to-date PGP/GnuPG key
+ <para>It is very important to have a current <acronym>PGP</acronym>/Gnu<acronym>PG</acronym> key
in the repository. The key may be required for
- positive identification of a committer, for example, by the
- &a.admins; for account recovery. A complete keyring of
+ positive identification of a committer. For example, the
+ &a.admins; might need it for account recovery. A complete keyring of
<systemitem
class="fqdomainname">FreeBSD.org</systemitem> users is
available for download from <link
xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para>
</note>
- </listitem>
+ </step>
- <listitem>
- <para>Add an entry for yourself to the current committers
- section of
- <filename>head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>,
+ <step>
+ <title>Update Mentor and Mentee Information</title>
+
+ <para><filename>head/share/misc/committers-<replaceable>repository</replaceable>.dot</filename> —
+ Add an entry to the current committers
+ section,
where <replaceable>repository</replaceable> is <literal>doc</literal>, <literal>ports</literal>, or <literal>src</literal>, depending on
- the commit privileges granted. Also add an entry for
- each of your mentor/mentee relationships in the
+ the commit privileges granted.</para>
+
+ <para>Add an entry for the
+ each additonal mentor/mentee relationship in the
bottom section.</para>
- </listitem>
+ </step>
- <listitem>
- <para>Some people add an entry for themselves to
- <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para>
- </listitem>
+ <step>
+ <title>Generate a <application>Kerberos</application>
+ Password</title>
+
+ <para>See <xref linkend="kerberos-ldap"/> to generate or
+ set a <application>Kerberos</application> for use with
+ other &os; services like the bug tracking
+ database.</para>
+ </step>
+
+ <step>
+ <title>Optional: Enable Wiki Account</title>
+
+ <para><link xlink:href="http://wiki.freebsd.org">&os; Wiki</link> Account —
+ A wiki account allows sharing projects and ideas. Those
+ who do not yet have an account can contact
+ <email>clusteradm at FreeBSD.org</email> to obtain
+ one.</para>
+ </step>
- <listitem>
- <para>Some people add an entry for themselves to
- <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para>
- </listitem>
+ <step>
+ <title>Optional: Update Wiki Information</title>
- <listitem>
- <para>If you already have an account at the
- <link xlink:href="http://wiki.freebsd.org">&os;
- wiki</link>, make sure your mentor moves you from the
- <link
- xlink:href="http://wiki.freebsd.org/ContributorsGroup">Contributors
- group</link> to the <link
- xlink:href="http://wiki.freebsd.org/DevelopersGroup">Developers
- group</link>. Otherwise, consider signing up for an
- account so you can publish projects and ideas you are
- working on.</para>
- </listitem>
-
- <listitem>
- <para>Once you get access to the wiki, you may add yourself
+ <para>Wiki Information -
+ After gaining access to the wiki, some people add entries
to the <link
xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
Got Here</link>,
@@ -2316,42 +2352,43 @@ ControlPersist yes</screen>
Nicks</link>, and <link
xlink:href="https://wiki.freebsd.org/DogsOfFreeBSD">Dogs
of FreeBSD</link> pages.</para>
- </listitem>
-
- <listitem>
- <para>If you subscribe to &a.svn-src-all.name;,
- &a.svn-ports-all.name; or &a.svn-doc-all.name;, you will
- probably want to unsubscribe to avoid receiving duplicate
- copies of commit messages and their followups.</para>
- </listitem>
- </itemizedlist>
+ </step>
- <note>
- <para>All <filename>src</filename> commits should go to
- &os.current; first before being merged to &os.stable;. No
- major new features or high-risk modifications should be made
- to the &os.stable; branch.</para>
- </note>
+ <step>
+ <title>Optional: Update Ports with Personal Information</title>
+ <para><filename>ports/astro/xearth/files/freebsd.committers.markers</filename> and
+ <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename> -
+ Some people add entries for themselves to these
+ files to show where they are located or the date of their birthday.</para>
+ </step>
+
+ <step>
+ <title>Optional: Prevent Duplicate Mailings</title>
+
+ <para>Subscribers to &a.svn-src-all.name;,
+ &a.svn-ports-all.name; or &a.svn-doc-all.name; might wish to
+ unsubscribe to avoid receiving duplicate
+ copies of commit messages and followups.</para>
+ </step>
+ </procedure>
</sect2>
<sect2 xml:id="conventions-everyone">
- <title>Guidelines for Everyone</title>
-
- <para>Whether or not you have commit rights:</para>
+ <title>For Everyone</title>
- <itemizedlist>
- <listitem>
+ <procedure xml:id="conventions-everyone-steps">
+ <step>
<para>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
- &os;. (You should also mention who your mentor will
- be). Email this to the &a.developers; and you will be on
+ 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
+ &os;, and who will be your mentor.
+ Email this to the &a.developers; and you will be on
your way!</para>
- </listitem>
+ </step>
- <listitem>
+ <step>
<para>Log into <systemitem>hub.FreeBSD.org</systemitem> and
create a
<filename>/var/forward/<replaceable>user</replaceable></filename>
@@ -2379,13 +2416,13 @@ ControlPersist yes</screen>
directory on <systemitem
class="fqdomainname">freefall.FreeBSD.org</systemitem>
to disable the checks for your email.</para>
- </listitem>
- </itemizedlist>
+ </step>
+ </procedure>
<note>
- <para>If you are a developer but not a committer, you will
+ <para>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
+ lists. The subscriptions are derived from the access
rights.</para>
</note>
</sect2>
@@ -2393,20 +2430,22 @@ ControlPersist yes</screen>
<sect2 xml:id="mentors">
<title>Mentors</title>
- <para>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
+ <para>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.</para>
- <para>For committers: until your mentor decides (and announces
- with a commit to <filename>mentors</filename>) 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
+ <para>For committers: do not commit anything without first
+ getting mentor approval. Document that
approval with an <literal>Approved by:</literal> line in the
commit message.</para>
+
+ <para>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 <filename>mentors</filename>.</para>
</sect2>
</sect1>
@@ -2434,7 +2473,7 @@ ControlPersist yes</screen>
<entry>The problem report (if any) which is affected
(typically, by being closed) by this commit. Only
include one PR per line as the automated scripts which
- parse this line can not understand more than
+ parse this line cannot understand more than
one.</entry>
</row>
@@ -3475,9 +3514,9 @@ Relnotes: yes</programlisting>
cases where the dispute involves a change to the codebase
and the participants do not appear to be reaching an
amicable agreement, core may appoint a mutually-agreeable
- 3rd party to resolve the dispute. All parties involved
+ third party to resolve the dispute. All parties involved
must then agree to be bound by the decision reached by
- this 3rd party.</para>
+ this third party.</para>
</listitem>
<listitem>
More information about the svn-doc-head
mailing list