Add the big list of rules that was thrashed out on -committers recently.

Final text was from JKH, I ran it through the txt2docbook filter.

1 files changed, 340 insertions, 0 deletions

diff --git a/en_US.ISO_8859-1/articles/committers-guide/article.sgml b/en_US.ISO_8859-1/articles/committers-guide/article.sgml
index 340ef10eeb..8457936750 100644
--- a/en_US.ISO_8859-1/articles/committers-guide/article.sgml
+++ b/en_US.ISO_8859-1/articles/committers-guide/article.sgml
@@ -439,4 +439,344 @@
       <filename>/usr/ports/security/ssh</filename>, &man.ssh.1;,
       &man.ssh-agent.1;, &man.scp.1;, and &man.ssh-keygen.1;.</para>
   </sect1>
+
+  <sect1>
+    <title>The FreeBSD committer's Big List of Rules</title>
+
+    <orderedlist>
+      <listitem>
+        <para>Respect other committers.</para>
+      </listitem>
+
+      <listitem>
+	<para>Discuss any significant change <emphasis>before</emphasis>
+	  committing.</para>
+      </listitem>
+
+      <listitem>
+	<para>Respect existing maintainers if listed
+	  (<makevar>MAINTAINER</makevar> field in
+	  <filename>Makefile</filename> or <filename>MAINTAINER</filename>
+	  file in the top-level directory).</para>
+      </listitem>
+
+      <listitem>
+	<para>Never touch the repository directly.  Ask a Repomeister.</para>
+      </listitem>
+
+      <listitem>
+	<para>Any disputed change must be backed out pending resolution of
+	  the dispute if requested by a maintainer or the Principal
+	  Architect.  Security related changes may override a maintainer's
+	  wishes at the Security Officer's discretion.</para>
+      </listitem>
+
+      <listitem>
+	<para>Changes go to -current before -stable unless specifically
+	  permitted by the release engineer or unless they're not applicable
+	  to -current.  Any non-trivial or non-urgent change which is
+	  applicable should also be allowed to sit in -current for at least 3
+	  days before merging so that it can be given sufficient testing.  The
+	  release engineer has the same authority over the -stable branch as
+	  outlined for the Principal Architect in rule #5.</para>
+      </listitem>
+
+      <listitem>
+	<para>Don't fight in public with other committers; it looks bad.  If
+	  you must "strongly disagree" about something, do so only in
+	  private.</para>
+      </listitem>
+
+      <listitem>
+	<para>Respect all code freezes and read the committers mailing list on
+	  a timely basis so you know when a code freeze is in effect.</para>
+      </listitem>
+
+      <listitem>
+	<para>When in doubt on any procedure, ask first!</para>
+      </listitem>
+
+      <listitem>
+	<para>Test your changes before committing them.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>As noted, breaking some of these rules can be grounds for suspension
+      or, upon repeated offense, permanent removal of commit privileges.
+      Three or more members of core, or the Principal Architect and another
+      member of core acting in unison, have the power to temporarily suspend
+      commit privileges until -core as a whole has the chance to review the
+      issue.  In cases of "emergency" (a committer doing damage to the
+      repository), a temporary suspension may also be done by the repository
+      meisters or any other member of core who may happen to be awake at the
+      time.  Only core as a whole has the authority to suspend commit
+      privileges for any significant length of time or to remove them
+      permanently, the latter generally only being done after consultation
+      with committers.  This rule does not exist to set core up as a bunch of
+      cruel dictators who can dispose of committers as casually as empty soda
+      cans, but to give the project a kind of safety fuse.  If someone is
+      seriously out of control, it's important to be able to deal with this
+      immediately rather than be paralyzed by debate.  In all cases, a
+      committer whose privileges are suspended or revoked is entitled to a
+      &ldquo;hearing&rdquo;, the total duration of the suspension being
+      determined at that time.  A committer whose privileges are suspended may
+      also request a review of the decision after 30 days and every 30 days
+      thereafter (unless the total suspension period is less than 30 days).  A
+      committer whose privileges have been revoked entirely may request a
+      review after a period of 6 months have elapsed.  This review policy is
+      <emphasis>strictly informal</emphasis> and, in all cases, core reserves
+      the right to either act on or disregard requests for review if they feel
+      their original decision to be the right one.</para>
+    
+    <para>In all other aspects of project operation, core is a subset of
+      committers and is bound by the <emphasis>same rules</emphasis>.  Just
+      because someone is in core doesn't mean that they have special
+      dispensation to step outside of any of the lines painted here; core's
+      &ldquo;special powers&rdquo; only kick in when it acts as a group, not
+      on an individual basis.  As individuals, we are all committers first and
+      core second.</para>
+    
+    <sect2>
+      <title>Details</title>
+
+      <orderedlist>
+	<listitem>
+	  <para>Respect other committers.</para>
+
+	  <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 doesn't get into committers 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
+	    <emphasis>treat</emphasis> other committers with respect at all
+	    times or the whole team structure rapidly breaks down.</para>
+	  
+	  <para>Being able to work together long term is this project's
+	    greatest asset, one far more important than any set of changes to
+	    the code, and turning arguments about code into issues that affect
+	    our long-term ability to work harmoniously together is just not
+	    worth the trade-off by any conceivable stretch of the
+	    imagination.</para>
+	  
+	  <para>To comply with this rule, don't send email when you're angry
+	    or otherwise behave in a manner which is likely to strike others
+	    as needlessly confrontational.  First calm down, then think about
+	    how to communicate in the most effective fashion for convincing
+	    the other person(s) that your side of the argument is correct,
+	    don't just blow off some steam so you can feel better in the short
+	    term at the cost of a long-term flame war.  Not only is this very
+	    bad &ldquo;energy economics&rdquo;, but repeated displays of
+	    public aggression which impair our ability to work well together
+	    will be dealt with severely by the project leadership and may
+	    result in suspension or termination of your commit privileges.
+	    That's never an option which the project's leadership enjoys in
+	    the slightest, but unity comes first.  No amount of code or good
+	    advice is worth trading that away.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Discuss any significant change <emphasis>before</emphasis>
+	    committing.</para>
+	  
+	  <para>The CVS repository is not where changes should be initially
+	    submitted for correctness or argued over, that should happen first
+	    in the mailing lists and then committed only once something
+	    resembling consensus has been reached.  This doesn't mean that you
+	    have to ask permission before correcting every obvious syntax
+	    error or man page misspelling, simply that you should try to
+	    develop a feel for when a proposed change isn't quite such a
+	    no-brainer and requires some feedback first.  People really don't
+	    mind sweeping changes if the result is something clearly better
+	    than what they had before, they just don't like being
+	    <emphasis>surprised</emphasis> by those changes.  The very best
+	    way of making sure that you're on the right track is to have your
+	    code reviewed by one or more other committers.</para>
+
+	  <para>When in doubt, ask for review!</para>
+	</listitem>
+
+	<listitem>
+	  <para>Respect existing maintainers if listed.</para>
+
+	  <para>Many parts of FreeBSD aren't &ldquo;owned&rdquo; in the sense
+	    that any specific individual will jump up and yell if you commit a
+	    change to &ldquo;their&rdquo; area, but it still pays to check
+	    first.  One convention we use is to put a maintainer line in the
+	    <filename>Makefile</filename> for any package or subtree which is
+	    being actively maintained by one or more people; see <ulink
+	      url="http://www.FreeBSD.org/handbook/policies.html">http://www.FreeBSD.org/handbook/policies.html</ulink>
+	    for documentation on this.  Where sections of code have several
+	    maintainers, commits to affected areas by one maintainer need to
+	    be reviewed by at least one other maintainer.  In cases where the
+	    "maintainer-ship" of something isn't clear, you can also look at
+	    the CVS logs for the file(s) in question and see if someone has
+	    been working recently or predominantly in that area.</para>
+
+	  <para>Other areas of FreeBSD fall under the control of someone who
+	    manages an overall category of FreeBSD evolution, such as
+	    internationalization or networking.  See
+	    <ulink
+	      url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.freebsd.org/handbook/staff-who.html</ulink> for more information on this.</para>
+	</listitem>
+	
+	<listitem>
+	  <para>Never touch the repository directly.  Ask a
+	    Repomeister.</para>
+
+	  <para>This is pretty clear - you're not allowed to make direct
+	    modifications to the CVS repository, period.  In case of
+	    difficulty, ask one of the repository meisters by sending mail to
+	    <email>cvs@freebsd.org</email> and simply wait for them to fix the
+	    problem and get back to you. Do not attempt to fix the problem
+	    yourself!</para>
+	  
+	  <para>If you're thinking about putting down a tag or doing a new
+	    import of code on a vendor branch, you might also find it useful
+	    to ask for advice first.  A lot of people get this wrong the first
+	    few times and the consequences are expensive in terms of files
+	    touched and angry CVSup/CTM folks who are suddenly getting a lot
+	    of changes sent over unnecessarily.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Any disputed change must be backed out pending resolution of
+	    the dispute if requested by a maintainer or the Principal
+	    Architect.  Security related changes may override a maintainer's
+	    wishes at the Security Officer's discretion.</para>
+	  
+	  <para>This may be hard to swallow in times of conflict (when each
+	    side is convinced that they're in the right, of course) but CVS
+	    makes it unnecessary to have an ongoing dispute raging when it's
+	    far easier to simply reverse the disputed change, get everyone
+	    calmed down again and then try and figure out how best to proceed.
+	    If the change turns out to be the best thing after all, it can be
+	    easily brought back. If it turns out not to be, then the users
+	    didn't have to live with the bogus change in the tree while
+	    everyone was busily debating its merits.  People very very rarely
+	    call for back-outs in the repository since discussion generally
+	    exposes bad or controversial changes before the commit even
+	    happens, but on such rare occasions the back-out should be done
+	    without argument so that we can get immediately on to the topic of
+	    figuring out whether it was bogus or not.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Changes go to -current before -stable unless specifically
+	    permitted by the release engineer or unless they're not applicable
+	    to -current.  Any non-trivial or non-urgent change which is
+	    applicable should also be allowed to sit in -current for at least
+	    3 days before merging so that it can be given sufficient testing.
+	    The release engineer has the same authority over the -stable
+	    branch as outlined in rule #5.</para>
+	
+	  <para>This is another "don't argue about it" issue since it's the
+	    release engineer who is ultimately responsible (and gets beaten
+	    up) if a change turns out to be bad.  Please respect this and give
+	    the release engineer your full cooperation when it comes to the
+	    -stable branch.  The management of -stable may frequently seem to
+	    be overly conservative to the casual observer, but also bear in
+	    mind the fact that conservatism is supposed to be the hallmark of
+	    -stable and different rules apply there than in -current.  There's
+	    also really no point in having -current be a testing ground if
+	    changes are merged over from -stable immediately without giving
+	    them a chance be tested by the -current developers, so allow some
+	    time to elapse before merging unless the -stable fix is critical,
+	    time sensitive or so obvious as to make further testing
+	    unnecessary (spelling fixes to manpages, obvious bug/typo fixes,
+	    etc.)  In other words, apply common sense.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Don't fight in public with other committers; it looks bad.  If
+	    you must &ldquo;strongly disagree&rdquo; about something, do so
+	    only in private.</para>
+	  
+	  <para>This project has a public image to uphold and that image is
+	    very important to all of us, especially if we're to continue to
+	    attract new members.  There will be occasions when, despite
+	    everyone's very best attempts at self-control, tempers are lost
+	    and angry words are exchanged, and the best we can do is try and
+	    minimize the effects of this until everyone has cooled back down.
+	    That means that you shouldn't air your angry words in public and
+	    you shouldn't forward private correspondence to public mailing
+	    lists or aliases.  What people say one-to-one is often much less
+	    sugar-coated than what they'd say in public, and such
+	    communications therefore have no place there - they only serve to
+	    inflame an already bad situation. If the person sending you a
+	    flame-o-gram had at least the grace to send it privately, then
+	    have the grace to keep it private yourself.  If you feel you're
+	    being unfairly treated by another developer and it's causing you
+	    anguish, bring the matter up with core rather than taking it
+	    public.  We'll do our 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 don't appear to be reaching an
+	    amicable agreement, core may appoint a mutually-agreeable 3rd
+	    party to resolve the dispute.  All parties involved must then
+	    agree to be bound by the decision reached by this 3rd
+	    party.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Respect all code freezes and read the committers mailing list
+	    on a timely basis so you know when they are.</para>
+	  
+	  <para>Committing changes during a code freeze is a really big
+	    mistake and committers are expected to keep up-to-date on what's
+	    going on before jumping in after a long absence and committing 10
+	    megabytes worth of accumulated stuff.  People who abuse this on a
+	    regular basis will have their commit privileges suspended until
+	    they get back from the FreeBSD Happy Reeducation Camp we run in
+	    Greenland.</para>
+	</listitem>
+
+	<listitem>
+	  <para>When in doubt on any procedure, ask first!</para>
+
+	  <para>So many mistakes are made because someone's in a hurry and
+	    just assumes they know the right way of going about something.  If
+	    you haven't done it before, chances are good that you don't
+	    actually know the way we do things and really need to ask first or
+	    you're going to completely embarrass yourself in public.  There's
+	    no shame in asking &ldquo;how in the heck do I do this?&rdquo; and
+	    we already know you're an intelligent person or you wouldn't be in
+	    committers.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Test your changes before committing them.</para>
+	  
+	  <para>This may sound obvious, but if it really were so obvious then
+	    we probably wouldn't see so many cases of people clearly not doing
+	    this.  If your changes are to the kernel, make sure you can still
+	    compile both GENERIC and LINT.  If your changes are anywhere else,
+	    make sure you can still make world.  If your changes are to a
+	    branch, make sure your testing occurs with a machine which is
+	    running that code.  If you have a change which also may break
+	    another architecture, be sure and test on all supported
+	    architectures.  Currently, this is only the x86 and the alpha so
+	    it's pretty easy to do.  If you need to test on the axp, your
+	    account on <hostid role="fqdn">beast.freebsd.org</hostid> will let
+	    you compile and test alpha binaries/kernels/etc.  As other
+	    architectures are added to the FreeBSD supported platforms list,
+	    the appropriate shared testing resources will be made
+	    available.</para>
+	</listitem>
+      </orderedlist>
+    </sect2>
+
+    <sect2>
+      <title>Other Suggestions</title>
+
+      <para>When committing documentation changes, also be sure and use a
+	spell checker before committing. :)  For all SGML docs, you should
+	also verify that your formatting directives are correct by running
+	<command>make lint</command>.</para>
+
+      <para>For all on-line manual pages, run 'manck' (from ports) over the
+	man page to verify the all of the cross references and file references
+	are correct and that the man page has all of the appropriate
+	<makevar>MLINK</makevar>s installed.</para>
+    </sect2>
+  </sect1>
 </article>