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

Round 1 (of 3) of changes to the committer's guide. Content changes

Browse source 
as follows:

RELENG_3 no longer a noteworthy tag.

Refer to repository meisters and SO team more consistently, less
dependence on individuals.

Don't refer to core as "we".

Comment to help out doc translation teams.

Move myself to RE team and consolidate "Who's Who" listings accordingly.

Security branch changes need to be approved by SO or RE teams.

Add mentions of developers list, where appropriate.

Wording tweaks.

Approved by:	jhb
This commit is contained in:
Bruce A. Mah 2002-04-28 17:55:20 +00:00
parent 6e11943177
commit 78d5cb767a
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=12892
1 changed files with 50 additions and 43 deletions

93
en_US.ISO8859-1/articles/committers-guide/article.sgml
View file

@ -64,19 +64,19 @@
</row>
<row>
<entry><emphasis>Main CVS Repository Meisters</emphasis></entry>
<entry>&a.peter; and &a.markm;, as well as &a.joe; and &a.asami; for
<entry><emphasis>Main &a.cvs;</emphasis></entry>
<entry>&a.peter; and &a.markm;, as well as &a.joe; for
<filename>ports/</filename></entry>
</row>
<row>
<entry><emphasis>Mailing List</emphasis></entry>
<entry><emphasis>Mailing Lists</emphasis></entry>
<entry>&a.developers;, &a.committers;</entry>
</row>
<row>
<entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
<entry>RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT)</entry>
<entry>RELENG_4 (4.x-STABLE), HEAD (-CURRENT)</entry>
</row>
</tbody>
</tgroup>
@ -160,7 +160,7 @@
<para>It is assumed that you are already familiar with the basic operation
of CVS.</para>
<para>The CVS Repository Meisters (Peter Wemm and John Polstra)
<para>The &a.cvs;
are the <quote>owners</quote> of the CVS repository and are
responsible for any and <emphasis>all</emphasis> direct
modification of it for the purposes of cleanup or fixing some
@ -168,11 +168,9 @@
attempt to touch the repository directly. Should you cause some
repository accident, say a bad cvs import or tag operation, do
<emphasis role="bold">not</emphasis> attempt to fix it yourself!
Mail or call John or Peter immediately and report the problem to
Mail the &a.cvs; (or call one of them) and report the problem to
one of them instead. The only ones allowed to directly fiddle
the repository bits are the repomeisters. Satoshi Asami is also a
repomeister for the <filename>ports/</filename> portion of the
tree.</para>
the repository bits are the repomeisters.</para>
<para>CVS operations are usually done by logging into
<hostid>freefall</hostid>, making sure the
@ -211,13 +209,13 @@
<para>If you need to use CVS <command>add</command> and
<command>delete</command> operations in a manner that is
effectively a <quote>mv</quote> operation, then a repository
copy is in order rather than your CVS <command>add</command> and
copy is in order rather than using CVS <command>add</command> and
<command>delete</command>. In a repository copy, a <link
linkend="conventions">CVS Meister</link> will copy the file(s)
to their new name and/or location and let you know when it is
done. The purpose of a repository copy is to preserve file
change history, or logs. We in the FreeBSD Project greatly
value the change history CVS gives to the project.</para>
value the change history that CVS gives to the project.</para>
<para>CVS reference information, tutorials, and FAQs can also be found at:
<ulink
@ -493,7 +491,7 @@
<para><emphasis>Watch the output of the <command>cvs
update</command> with care.</emphasis> The letter in front of
each file name indicates what was done with it:</para>
each filename indicates what was done with it:</para>
<informaltable frame="none">
<tgroup cols=2>
@ -585,11 +583,11 @@
</itemizedlist>
<para>You will almost certainly get a conflict because
of the <literal>$Id: article.sgml,v 1.108 2002-04-11 20:18:59 brian Exp $</literal> (or in FreeBSD's case,
of the <literal>$Id: article.sgml,v 1.109 2002-04-28 17:55:20 bmah Exp $</literal> (or in FreeBSD's case,
<literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>) lines, so you will have to edit
the file to resolve the conflict (remove the marker lines and
the second <literal>$Id: article.sgml,v 1.108 2002-04-11 20:18:59 brian Exp $</literal> line, leaving the original
<literal>$Id: article.sgml,v 1.108 2002-04-11 20:18:59 brian Exp $</literal> line intact).</para>
the second <literal>$Id: article.sgml,v 1.109 2002-04-28 17:55:20 bmah Exp $</literal> line, leaving the original
<literal>$Id: article.sgml,v 1.109 2002-04-28 17:55:20 bmah Exp $</literal> line intact).</para>
</listitem>
<listitem>
@ -755,11 +753,14 @@
<para>Avoid committing style or whitespace fixes and
functionality fixes in one go. It makes merging difficult,
and also makes it harder to understand just what functional
changes were made.</para>
changes were made. In the case of documentation files, it
can make the job of the translation teams more complicated,
as it becomes difficult for them to detemrine exactly what
content changes need to be translated.</para>
<para>Avoid committing changes to multiple files in one go
with a generic, vague message. Instead, commit each file (or
small groups of files) with tailored commit messages.</para>
small, related groups of files) with tailored commit messages.</para>
<para>Before committing, <emphasis>always</emphasis>:</para>
@ -855,7 +856,7 @@ checkout -P</programlisting>
that it is actually merely the Newtonian manifestation of a
sentient transdimensional entity. It is not humanly possible
to know its every quirk inside out, so do not be afraid to ask
the resident AI (&a.cvs;) for help when you screw up.</para>
the resident AI (&a.cvs;) for help.</para>
</listitem>
<listitem>
@ -938,6 +939,12 @@ checkout -P</programlisting>
without warning, so forward it or read it and you will not lose
it.</para>
</listitem>
<listitem>
<para>If you are subscribed to the &a.cvsall;, you will
probably want to unsubscribe to avoid receiving duplicate
copies of commit messages and their followups.</para>
</listitem>
</itemizedlist>
<para>All new committers also have a mentor assigned to them for
@ -1115,8 +1122,8 @@ docs:Documentation Bug:nik:</programlisting>
<screen>&prompt.root; <userinput>query-pr -c docs -s open</userinput></screen>
<para>Other interfaces, like
<filename>ports/databases/tkgnats</filename> should also work
<para>Other interfaces, such as that provided by the
<filename>ports/databases/tkgnats</filename> port should also work
nicely.</para>
</step>
@ -1135,8 +1142,8 @@ docs:Documentation Bug:nik:</programlisting>
<sect1 id="people">
<title>Who's Who</title>
<para>Besides Peter Wemm and John Polstra, the repository
meisters, there are other FreeBSD project members whom you will
<para>Besides the repository
meisters, there are other FreeBSD project members and teams whom you will
probably get to know in your role as a committer. Briefly,
and by no means all-inclusively, these are:</para>
@ -1172,11 +1179,11 @@ docs:Documentation Bug:nik:</programlisting>
<listitem>
<para>Nik oversees the
<ulink url="../../../../docproj/index.html">Doc. Project</ulink>.
<ulink url="../../../../docproj/index.html">Documentation Project</ulink>.
As well as writing documentation he put together the
infrastructure under <filename>doc/share/mk</filename> and the
stylesheets and related code under
<filename>doc/share/sgml</filename>. If you have got questions
<filename>doc/share/sgml</filename>. If you have questions
about these you are encouraged to send them via the &a.doc;.
Committers interested in contributing to the documentation should
familiarise themselves with the
@ -1233,6 +1240,7 @@ docs:Documentation Bug:nik:</programlisting>
<term>&a.steve;</term>
<term>&a.rwatson;</term>
<term>&a.jhb;</term>
<term>&a.bmah;</term>
<listitem>
<para>These are the members of the &a.re;. This team is
@ -1243,14 +1251,8 @@ docs:Documentation Bug:nik:</programlisting>
there is something you want merged from &os.current; to
&os.stable; (whatever values those may have at any given
time), these are the people to talk to about it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&a.bmah;</term>
<listitem>
<para>Bruce is keeper of the release documentation
<para>Bruce is also the keeper of the release documentation
(<filename>src/release/doc/*</filename>). If you commit a
change that you think is worthy of mention in the release notes,
please make sure Bruce knows about it. Better still, send him
@ -1301,7 +1303,7 @@ docs:Documentation Bug:nik:</programlisting>
<para>Jacques is the
<ulink url="../../../../security/">FreeBSD Security
Officer</ulink>
and oversees the Security Officer Team.
and oversees the &a.security-officer;.
</para>
</listitem>
</varlistentry>
@ -1336,7 +1338,7 @@ docs:Documentation Bug:nik:</programlisting>
<para>developers is all committers. This list was created to be a
forum for the committers <quote>community</quote> issues.
Examples are Core
voting, announcements, etc... developers@FreeBSD.org is
voting, announcements, etc. This listis
<emphasis>not</emphasis> intended as a place for code reviews or a
replacement for the &a.arch; or the &a.audit;. In fact
using it as such hurts the FreeBSD Project as it gives a sense of a
@ -1372,7 +1374,7 @@ docs:Documentation Bug:nik:</programlisting>
<step>
<para>If you do not wish to type your password in every
time you use &man.ssh.1;, and you use RSA keys to
time you use &man.ssh.1;, and you use RSA or DSA keys to
authenticate, &man.ssh-agent.1; is there for your
convenience. If you want to use &man.ssh-agent.1;, make
sure that you run it before running other applications. X
@ -1384,7 +1386,7 @@ docs:Documentation Bug:nik:</programlisting>
<step>
<para>Generate a key pair using &man.ssh-keygen.1;. The key
pair will wind up in the
pair will wind up in your
<filename><envar>$HOME</envar>/.ssh</filename>
directory.</para>
</step>
@ -1476,7 +1478,7 @@ docs:Documentation Bug:nik:</programlisting>
<listitem>
<para>Respect all code freezes and read the
<literal>committers</literal> mailing list in a timely manner
<literal>committers</literal> and <literal>developers</literal> mailing lists in a timely manner
so you know when a code freeze is in effect.</para>
</listitem>
@ -1503,7 +1505,7 @@ docs:Documentation Bug:nik:</programlisting>
commit privileges. Three or more members of core
acting in unison,
have the power to temporarily suspend commit privileges until
<literal>-core</literal> as a whole has the chance to review the
core as a whole has the chance to review the
issue. In case of an <quote>emergency</quote> (a committer
doing damage to the repository), a temporary suspension may also
be done by the repository meisters or any other member of core
@ -1535,7 +1537,7 @@ docs:Documentation Bug:nik:</programlisting>
that they have special dispensation to step outside of any of
the lines painted here; core's <quote>special powers</quote>
only kick in when it acts as a group, not on an individual
basis. As individuals, we are all committers first and core
basis. As individuals, the core team members are all committers first and core
second.</para>
<sect2>
@ -1548,7 +1550,7 @@ docs:Documentation Bug:nik:</programlisting>
<para>This means that you need to treat other committers as
the peer-group developers that they are. Despite our
occasional attempts to prove the contrary, one does not get
into committers by being stupid and nothing rankles more
to be a committer by being stupid and nothing rankles more
than being treated that way by one of your peers. Whether
we always feel respect for one another or not (and
everyone has off days), we still have to
@ -1728,6 +1730,11 @@ docs:Documentation Bug:nik:</programlisting>
time sensitive or so obvious as to make further testing
unnecessary (spelling fixes to man pages, obvious bug/typo
fixes, etc.) In other words, apply common sense.</para>
<para>Changes to the security branches
(for example, <literal>RELENG_4_5</literal>) must be
approved by a member of the &a.security-officer;, or in
some cases, by a member of the &a.re;.</para>
</listitem>
<listitem>
@ -1753,7 +1760,7 @@ docs:Documentation Bug:nik:</programlisting>
then have the grace to keep it private yourself. If you
feel you are being unfairly treated by another developer,
and it is causing you anguish, bring the matter up with
core rather than taking it public. We will do our best to
core rather than taking it public. Core will do its best to
play peace makers and get things back to sanity. In cases
where the dispute involves a change to the codebase and
the participants do not appear to be reaching an amicable
@ -1765,10 +1772,10 @@ docs:Documentation Bug:nik:</programlisting>
<listitem>
<para>Respect all code freezes and read the
<literal>committers</literal> mailing list on a timely
basis so you know when they are.</para>
<literal>committers</literal> and <literal>developers</literal> mailing list on a timely
basis so you know when a code freeze is in effect.</para>
<para>Committing changes during a code freeze is a really
<para>Committing unapproved changes during a code freeze is a really
big mistake and committers are expected to keep up-to-date
on what is going on before jumping in after a long absence
and committing 10 megabytes worth of accumulated stuff.