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
Download patch file Download diff file Expand all files Collapse all files

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

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