os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Clarify and organize the steps for new committers.

Browse source
This commit is contained in:
Warren Block 2014-06-24 13:20:27 +00:00
parent 3cacb3b82e
commit 897a8350aa
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45109
1 changed files with 190 additions and 151 deletions
Download patch file Download diff file Expand all files Collapse all files

331
en_US.ISO8859-1/articles/committers-guide/article.xml
View file

@ -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@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 secret key.</screen>
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 secret key.</screen>
<email>accounts@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 secret key.</screen>
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>Those who have been given commit rights to the &os;
repositories must follow these steps.</para>
<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>
<itemizedlist xml:id="commit-notes">
<listitem>
<para>Get mentor approval before committing each of these
changes!</para>
</listitem>
<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>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>
<para>This is a relatively easy task, but remains a good
first test of your version control skills.</para>
<important>
<listitem>
<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
<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 &quot;auto-props&quot; entries
from <filename>auto-props.txt</filename> mentioned
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>
</important>
<note>
<para>Do not forget to get mentor approval for these
patches!</para>
</note>
</listitem>
<listitem>
<para>Add yourself to the <quote>Developers</quote> section
<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> &mdash;
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> &mdash;
Add an entry 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>
</listitem>
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> &mdash;
Remove the entry from the
<quote>Additional Contributors</quote> section.
Entries are sorted by last name.</para>
</step>
<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>
</listitem>
<step>
<title>Add a News Item</title>
<para><filename>doc/head/share/xml/news.xml</filename> &mdash;
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@FreeBSD.org</email>.</para>
</step>
<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>
<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> &mdash;
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>
<listitem>
<para>Some people add an entry for themselves to
<filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para>
</listitem>
<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>
<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>
<step>
<title>Optional: Enable Wiki Account</title>
<listitem>
<para>Once you get access to the wiki, you may add yourself
<para><link xlink:href="http://wiki.freebsd.org">&os; Wiki</link> Account &mdash;
A wiki account allows sharing projects and ideas. Those
who do not yet have an account can contact
<email>clusteradm@FreeBSD.org</email> to obtain
one.</para>
</step>
<step>
<title>Optional: Update Wiki Information</title>
<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>
</step>
<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>
<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>
<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: 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>
<title>For Everyone</title>
<para>Whether or not you have commit rights:</para>
<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>
@ -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>