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

Whitespace cleanups. Translators can ignore.

Browse source
This commit is contained in:
John Baldwin 2000-02-03 02:38:10 +00:00
parent ca05ae7e42
commit de56fa420c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=6482
2 changed files with 718 additions and 598 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -185,10 +185,13 @@
(where <replaceable>user</replaceable> is your username) file (where <replaceable>user</replaceable> is your username) file
containing the e-mail address where you want mail addressed containing the e-mail address where you want mail addressed
to <replaceable>yourusername</replaceable>@FreeBSD.org to <replaceable>yourusername</replaceable>@FreeBSD.org
to be forwarded. This includes all of the commit messages as well as any other mail addressed to <email>cvs-committers@FreeBSD.org</email>. Really large mailboxes which have taken up to be forwarded. This includes all of the commit messages as
permanent residence on <hostid>hub</hostid> often get well as any other mail addressed to
<quote>accidently</quote> truncated without warning, so forward <email>cvs-committers@FreeBSD.org</email>. Really large
it or read it and you will not lose it.</para> mailboxes which have taken up permanent residence on
<hostid>hub</hostid> often get <quote>accidently</quote>
truncated without warning, so forward it or read it and you will
not lose it.</para>
<para>All new committers also have a mentor assigned to them for <para>All new committers also have a mentor assigned to them for
the first few months. Your mentor is more or less responsible for the first few months. Your mentor is more or less responsible for
@ -216,15 +219,20 @@
areas, to our shame), the same applies. If, however, you are areas, to our shame), the same applies. If, however, you are
about to modify something which is clearly being actively about to modify something which is clearly being actively
maintained by someone else (and it is only by watching the maintained by someone else (and it is only by watching the
<literal>cvs-committers</literal> mailing list that you can really get <literal>cvs-committers</literal> mailing list that you can
a feel for just what is and is not) then consider sending the really get a feel for just what is and is not) then consider
change to them instead, just as you would have before becoming a sending the change to them instead, just as you would have
committer. For ports, you should contact the listed before becoming a committer. For ports, you should contact the
<makevar>MAINTAINER</makevar> in the listed <makevar>MAINTAINER</makevar> in the
<filename>Makefile</filename>. For other parts of the <filename>Makefile</filename>. For other parts of the
repository, if you are unsure who the active maintainer might repository, if you are unsure who the active maintainer might
be, it may help to scan the output of <command>cvs log</command> be, it may help to scan the output of <command>cvs log</command>
to see who has committed changes in the past. &a.fenner; has written a nice shell script that can help determine who the active maintainer might be. It lists each person who has committed to a given file along with the number of commits each person has made. It can be found on <hostid>freefall</hostid> at <filename>~fenner/bin/whodid</filename>. If your queries go to see who has committed changes in the past. &a.fenner; has
written a nice shell script that can help determine who the
active maintainer might be. It lists each person who has
committed to a given file along with the number of commits each
person has made. It can be found on <hostid>freefall</hostid>
at <filename>~fenner/bin/whodid</filename>. If your queries go
unanswered or the committer otherwise indicates a lack of unanswered or the committer otherwise indicates a lack of
proprietary interest in the area affected, go ahead and commit proprietary interest in the area affected, go ahead and commit
it.</para> it.</para>
@ -289,10 +297,11 @@
<term>&a.asami;</term> <term>&a.asami;</term>
<listitem> <listitem>
<para>Satoshi is the Ports Wraith, meaning that he has ultimate <para>Satoshi is the Ports Wraith, meaning that he has
authority over any modifications to the ports collection or ultimate authority over any modifications to the ports
the ports skeleton makefiles. He is also the one responsible for collection or the ports skeleton makefiles. He is also
administering code freezes before the releases.</para> the one responsible for administering code freezes before
the releases.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -300,9 +309,9 @@
<term>&a.bde;</term> <term>&a.bde;</term>
<listitem> <listitem>
<para>Bruce is the Obersturmbahnfuhrer of the Style Police. When you <para>Bruce is the Obersturmbahnfuhrer of the Style Police.
do a commit that could have been done better, Bruce will When you do a commit that could have been done better,
be there to tell you. Be thankful that someone Bruce will be there to tell you. Be thankful that someone
is.</para> is.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -311,14 +320,13 @@
<term>&a.dg;</term> <term>&a.dg;</term>
<listitem> <listitem>
<para>David is our principal architect and overseer of the VM <para>David is our principal architect and overseer of the
system. If you have a VM system change in mind, VM system. If you have a VM system change in mind,
coordinate it with David. Should you become locked in a coordinate it with David. Should you become locked in a
bitter, intractable dispute with some other committer over bitter, intractable dispute with some other committer over
a proposed change (which does not happen very often, a proposed change (which does not happen very often,
thankfully) then an appeal to David to put on his P.A. hat thankfully) then an appeal to David to put on his P.A. hat
and make a final decision might be and make a final decision might be necessary.</para>
necessary.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -399,14 +407,15 @@
</step> </step>
<step> <step>
<para>If you do not wish to to type your password in every time <para>If you do not wish to to type your password in every
you use &man.ssh.1;, and you use RSA keys to authenticate, time you use &man.ssh.1;, and you use RSA keys to
&man.ssh-agent.1; is there for your convenience. If authenticate, &man.ssh-agent.1; is there for your
you want to use &man.ssh-agent.1;, make sure that you run it convenience. If you want to use &man.ssh-agent.1;, make
before running other applications. X users, for example, sure that you run it before running other applications. X
usually do this from their <filename>.xsession</filename> or users, for example, usually do this from their
<filename>.xinitrc</filename> file. <filename>.xsession</filename> or
See &man.ssh-agent.1; for details.</para> <filename>.xinitrc</filename> file. See &man.ssh-agent.1;
for details.</para>
</step> </step>
<step> <step>
@ -453,47 +462,54 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Discuss any significant change <emphasis>before</emphasis> <para>Discuss any significant change
committing.</para> <emphasis>before</emphasis> committing.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect existing maintainers if listed in the <para>Respect existing maintainers if listed in the
(<makevar>MAINTAINER</makevar> field in (<makevar>MAINTAINER</makevar> field in
<filename>Makefile</filename> or in the <filename>MAINTAINER</filename> <filename>Makefile</filename> or in the
file in the top-level directory).</para> <filename>MAINTAINER</filename> file in the top-level
directory).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Never touch the repository directly. Ask a Repomeister.</para> <para>Never touch the repository directly. Ask a
Repomeister.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Any disputed change must be backed out pending resolution of <para>Any disputed change must be backed out pending
the dispute if requested by a maintainer or the Principal resolution of the dispute if requested by a maintainer or
Architect. Security related changes may override a maintainer's the Principal Architect. Security related changes may
wishes at the Security Officer's discretion.</para> override a maintainer's wishes at the Security Officer's
discretion.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically <para>Changes go to <literal>-CURRENT</literal> before
permitted by the release engineer or unless they're not applicable <literal>-STABLE</literal> unless specifically permitted by
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is the release engineer or unless they're not applicable to
applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least 3 <literal>-CURRENT</literal>. Any non-trivial or non-urgent
days before merging so that it can be given sufficient testing. The change which is applicable should also be allowed to sit in
release engineer has the same authority over the <literal>-STABLE</literal> branch as <literal>-CURRENT</literal> for at least 3 days before
outlined for the Principal Architect in rule #5.</para> merging so that it can be given sufficient testing. The
release engineer has the same authority over the
<literal>-STABLE</literal> branch as outlined for the
Principal Architect in rule #5.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Don't fight in public with other committers; it looks bad. If <para>Don't fight in public with other committers; it looks
you must <quote>strongly disagree</quote> about something, do so only in bad. If you must <quote>strongly disagree</quote> about
private.</para> something, do so only in private.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the <literal>committers</literal> mailing list on <para>Respect all code freezes and read the
a timely basis so you know when a code freeze is in effect.</para> <literal>committers</literal> mailing list on a timely basis
so you know when a code freeze is in effect.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -505,40 +521,45 @@
</listitem> </listitem>
</orderedlist> </orderedlist>
<para>As noted, breaking some of these rules can be grounds for suspension <para>As noted, breaking some of these rules can be grounds for
or, upon repeated offense, permanent removal of commit privileges. suspension or, upon repeated offense, permanent removal of
Three or more members of core, or the Principal Architect and another commit privileges. Three or more members of core, or the
member of core acting in unison, have the power to temporarily suspend Principal Architect and another member of core acting in unison,
commit privileges until <literal>-core</literal> as a whole has the chance to review the have the power to temporarily suspend commit privileges until
issue. In case of an <quote>emergency</quote> (a committer doing damage to the <literal>-core</literal> as a whole has the chance to review the
repository), a temporary suspension may also be done by the repository issue. In case of an <quote>emergency</quote> (a committer
meisters or any other member of core who may happen to be awake at the doing damage to the repository), a temporary suspension may also
time. Only core as a whole has the authority to suspend commit be done by the repository meisters or any other member of core
privileges for any significant length of time or to remove them who may happen to be awake at the time. Only core as a whole
permanently, the latter generally only being done after consultation has the authority to suspend commit privileges for any
with committers. This rule does not exist to set core up as a bunch of significant length of time or to remove them permanently, the
cruel dictators who can dispose of committers as casually as empty soda latter generally only being done after consultation with
cans, but to give the project a kind of safety fuse. If someone is committers. This rule does not exist to set core up as a bunch
seriously out of control, it's important to be able to deal with this of cruel dictators who can dispose of committers as casually as
immediately rather than be paralyzed by debate. In all cases, a empty soda cans, but to give the project a kind of safety fuse.
committer whose privileges are suspended or revoked is entitled to a If someone is seriously out of control, it's important to be
<quote>hearing</quote>, the total duration of the suspension being able to deal with this immediately rather than be paralyzed by
determined at that time. A committer whose privileges are suspended may debate. In all cases, a committer whose privileges are
also request a review of the decision after 30 days and every 30 days suspended or revoked is entitled to a <quote>hearing</quote>,
thereafter (unless the total suspension period is less than 30 days). A the total duration of the suspension being determined at that
committer whose privileges have been revoked entirely may request a time. A committer whose privileges are suspended may also
review after a period of 6 months have elapsed. This review policy is request a review of the decision after 30 days and every 30 days
<emphasis>strictly informal</emphasis> and, in all cases, core reserves thereafter (unless the total suspension period is less than 30
the right to either act on or disregard requests for review if they feel days). A committer whose privileges have been revoked entirely
their original decision to be the right one.</para> 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 <para>In all other aspects of project operation, core is a subset
committers and is bound by the <emphasis>same rules</emphasis>. Just of committers and is bound by the <emphasis>same
because someone is in core doesn't mean that they have special rules</emphasis>. Just because someone is in core doesn't mean
dispensation to step outside of any of the lines painted here; core's that they have special dispensation to step outside of any of
<quote>special powers</quote> only kick in when it acts as a group, not the lines painted here; core's <quote>special powers</quote>
on an individual basis. As individuals, we are all committers first and only kick in when it acts as a group, not on an individual
core second.</para> basis. As individuals, we are all committers first and core
second.</para>
<sect2> <sect2>
<title>Details</title> <title>Details</title>
@ -547,55 +568,61 @@
<listitem> <listitem>
<para>Respect other committers.</para> <para>Respect other committers.</para>
<para>This means that you need to treat other committers as the <para>This means that you need to treat other committers as
peer-group developers that they are. Despite our occasional the peer-group developers that they are. Despite our
attempts to prove the contrary, one doesn't get into committers by occasional attempts to prove the contrary, one doesn't get
being stupid and nothing rankles more than being treated that way into committers by being stupid and nothing rankles more
by one of your peers. Whether we always feel respect for one than being treated that way by one of your peers. Whether
another or not (and everyone has off days), we still have to we always feel respect for one another or not (and
<emphasis>treat</emphasis> other committers with respect at all everyone has off days), we still have to
times or the whole team structure rapidly breaks down.</para> <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 <para>Being able to work together long term is this project's
greatest asset, one far more important than any set of changes to greatest asset, one far more important than any set of
the code, and turning arguments about code into issues that affect changes to the code, and turning arguments about code into
our long-term ability to work harmoniously together is just not issues that affect our long-term ability to work
worth the trade-off by any conceivable stretch of the harmoniously together is just not worth the trade-off by
imagination.</para> any conceivable stretch of the imagination.</para>
<para>To comply with this rule, don't send email when you're angry <para>To comply with this rule, don't send email when you're
or otherwise behave in a manner which is likely to strike others angry or otherwise behave in a manner which is likely to
as needlessly confrontational. First calm down, then think about strike others as needlessly confrontational. First calm
how to communicate in the most effective fashion for convincing down, then think about how to communicate in the most
the other person(s) that your side of the argument is correct, effective fashion for convincing the other person(s) that
don't just blow off some steam so you can feel better in the short your side of the argument is correct, don't just blow off
term at the cost of a long-term flame war. Not only is this very some steam so you can feel better in the short term at the
bad <quote>energy economics</quote>, but repeated displays of cost of a long-term flame war. Not only is this very bad
public aggression which impair our ability to work well together <quote>energy economics</quote>, but repeated displays of
will be dealt with severely by the project leadership and may public aggression which impair our ability to work well
result in suspension or termination of your commit privileges. together will be dealt with severely by the project
That's never an option which the project's leadership enjoys in leadership and may result in suspension or termination of
the slightest, but unity comes first. No amount of code or good your commit privileges. That's never an option which the
advice is worth trading that away.</para> 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>
<listitem> <listitem>
<para>Discuss any significant change <emphasis>before</emphasis> <para>Discuss any significant change
committing.</para> <emphasis>before</emphasis> committing.</para>
<para>The CVS repository is not where changes should be initially <para>The CVS repository is not where changes should be
submitted for correctness or argued over, that should happen first initially submitted for correctness or argued over, that
in the mailing lists and then committed only once something should happen first in the mailing lists and then
resembling consensus has been reached. This doesn't mean that you committed only once something resembling consensus has
have to ask permission before correcting every obvious syntax been reached. This doesn't mean that you have to ask
error or man page misspelling, simply that you should try to permission before correcting every obvious syntax error or
develop a feel for when a proposed change isn't quite such a man page misspelling, simply that you should try to
no-brainer and requires some feedback first. People really don't develop a feel for when a proposed change isn't quite such
mind sweeping changes if the result is something clearly better a no-brainer and requires some feedback first. People
than what they had before, they just don't like being really don't mind sweeping changes if the result is
<emphasis>surprised</emphasis> by those changes. The very best something clearly better than what they had before, they
way of making sure that you're on the right track is to have your just don't like being <emphasis>surprised</emphasis> by
code reviewed by one or more other committers.</para> 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> <para>When in doubt, ask for review!</para>
</listitem> </listitem>
@ -603,168 +630,191 @@
<listitem> <listitem>
<para>Respect existing maintainers if listed.</para> <para>Respect existing maintainers if listed.</para>
<para>Many parts of FreeBSD aren't <quote>owned</quote> in the sense <para>Many parts of FreeBSD aren't <quote>owned</quote> in
that any specific individual will jump up and yell if you commit a the sense that any specific individual will jump up and
change to <quote>their</quote> area, but it still pays to check yell if you commit a change to <quote>their</quote> area,
first. One convention we use is to put a maintainer line in the but it still pays to check first. One convention we use
<filename>Makefile</filename> for any package or subtree which is is to put a maintainer line in the
being actively maintained by one or more people; see <ulink <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> 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 for documentation on this. Where sections of code have
maintainers, commits to affected areas by one maintainer need to several maintainers, commits to affected areas by one
be reviewed by at least one other maintainer. In cases where the maintainer need to be reviewed by at least one other
<quote>maintainer-ship</quote> of something isn't clear, you can also look at maintainer. In cases where the
the CVS logs for the file(s) in question and see if someone has <quote>maintainer-ship</quote> of something isn't clear,
been working recently or predominantly in that area.</para> 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 <para>Other areas of FreeBSD fall under the control of
manages an overall category of FreeBSD evolution, such as someone who manages an overall category of FreeBSD
internationalization or networking. See evolution, such as internationalization or networking.
<ulink See <ulink url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.FreeBSD.org/handbook/staff-who.html</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> for more information on this.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Never touch the repository directly. Ask a <para>Never touch the repository directly. Ask a
Repomeister.</para> Repomeister.</para>
<para>This is pretty clear - you're not allowed to make direct <para>This is pretty clear - you're not allowed to make
modifications to the CVS repository, period. In case of direct modifications to the CVS repository, period. In
difficulty, ask one of the repository meisters by sending mail to case of difficulty, ask one of the repository meisters by
<email>cvs@FreeBSD.org</email> and simply wait for them to fix the sending mail to <email>cvs@FreeBSD.org</email> and simply
problem and get back to you. Do not attempt to fix the problem wait for them to fix the problem and get back to you. Do
yourself!</para> not attempt to fix the problem yourself!</para>
<para>If you're thinking about putting down a tag or doing a new <para>If you're thinking about putting down a tag or doing a
import of code on a vendor branch, you might also find it useful new import of code on a vendor branch, you might also find
to ask for advice first. A lot of people get this wrong the first it useful to ask for advice first. A lot of people get
few times and the consequences are expensive in terms of files this wrong the first few times and the consequences are
touched and angry CVSup/CTM folks who are suddenly getting a lot expensive in terms of files touched and angry CVSup/CTM
of changes sent over unnecessarily.</para> folks who are suddenly getting a lot of changes sent over
unnecessarily.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Any disputed change must be backed out pending resolution of <para>Any disputed change must be backed out pending
the dispute if requested by a maintainer or the Principal resolution of the dispute if requested by a maintainer or
Architect. Security related changes may override a maintainer's the Principal Architect. Security related changes may
wishes at the Security Officer's discretion.</para> 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 <para>This may be hard to swallow in times of conflict (when
side is convinced that they're in the right, of course) but CVS each side is convinced that they're in the right, of
makes it unnecessary to have an ongoing dispute raging when it's course) but CVS makes it unnecessary to have an ongoing
far easier to simply reverse the disputed change, get everyone dispute raging when it's far easier to simply reverse the
calmed down again and then try and figure out how best to proceed. disputed change, get everyone calmed down again and then
If the change turns out to be the best thing after all, it can be try and figure out how best to proceed. If the change
easily brought back. If it turns out not to be, then the users turns out to be the best thing after all, it can be easily
didn't have to live with the bogus change in the tree while brought back. If it turns out not to be, then the users
everyone was busily debating its merits. People very very rarely didn't have to live with the bogus change in the tree
call for back-outs in the repository since discussion generally while everyone was busily debating its merits. People
exposes bad or controversial changes before the commit even very very rarely call for back-outs in the repository
happens, but on such rare occasions the back-out should be done since discussion generally exposes bad or controversial
without argument so that we can get immediately on to the topic of changes before the commit even happens, but on such rare
figuring out whether it was bogus or not.</para> 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>
<listitem> <listitem>
<para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically <para>Changes go to <literal>-CURRENT</literal> before
permitted by the release engineer or unless they're not applicable <literal>-STABLE</literal> unless specifically permitted
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is by the release engineer or unless they're not applicable
applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least to <literal>-CURRENT</literal>. Any non-trivial or
3 days before merging so that it can be given sufficient testing. non-urgent change which is applicable should also be
The release engineer has the same authority over the <literal>-STABLE</literal> allowed to sit in <literal>-CURRENT</literal> for at least
branch as outlined in rule #5.</para> 3 days before merging so that it can be given sufficient
testing. The release engineer has the same authority over
the <literal>-STABLE</literal> branch as outlined in rule
#5.</para>
<para>This is another <quote>don't argue about it</quote> issue since it's the <para>This is another <quote>don't argue about it</quote>
release engineer who is ultimately responsible (and gets beaten issue since it's the release engineer who is ultimately
up) if a change turns out to be bad. Please respect this and give responsible (and gets beaten up) if a change turns out to
the release engineer your full cooperation when it comes to the be bad. Please respect this and give the release engineer
<literal>-STABLE</literal> branch. The management of <literal>-STABLE</literal> may frequently seem to your full cooperation when it comes to the
be overly conservative to the casual observer, but also bear in <literal>-STABLE</literal> branch. The management of
mind the fact that conservatism is supposed to be the hallmark of <literal>-STABLE</literal> may frequently seem to be
<literal>-STABLE</literal> and different rules apply there than in <literal>-CURRENT</literal>. There's overly conservative to the casual observer, but also bear
also really no point in having <literal>-CURRENT</literal> be a testing ground if in mind the fact that conservatism is supposed to be the
changes are merged over to <literal>-STABLE</literal> immediately. Changes need hallmark of <literal>-STABLE</literal> and different rules
a chance to be tested by the <literal>-CURRENT</literal> developers, so allow some apply there than in <literal>-CURRENT</literal>. There's
time to elapse before merging unless the <literal>-STABLE</literal> fix is critical, also really no point in having <literal>-CURRENT</literal>
be a testing ground if changes are merged over to
<literal>-STABLE</literal> immediately. Changes need a
chance to be tested by the <literal>-CURRENT</literal>
developers, so allow some time to elapse before merging
unless the <literal>-STABLE</literal> fix is critical,
time sensitive or so obvious as to make further testing time sensitive or so obvious as to make further testing
unnecessary (spelling fixes to manpages, obvious bug/typo fixes, unnecessary (spelling fixes to manpages, obvious bug/typo
etc.) In other words, apply common sense.</para> fixes, etc.) In other words, apply common sense.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Don't fight in public with other committers; it looks bad. If <para>Don't fight in public with other committers; it looks
you must <quote>strongly disagree</quote> about something, do so bad. If you must <quote>strongly disagree</quote> about
only in private.</para> something, do so only in private.</para>
<para>This project has a public image to uphold and that image is <para>This project has a public image to uphold and that
very important to all of us, especially if we are to continue to image is very important to all of us, especially if we are
attract new members. There will be occasions when, despite to continue to attract new members. There will be
everyone's very best attempts at self-control, tempers are lost occasions when, despite everyone's very best attempts at
and angry words are exchanged, and the best we can do is try and self-control, tempers are lost and angry words are
minimize the effects of this until everyone has cooled back down. exchanged, and the best we can do is try and minimize the
That means that you should not air your angry words in public and effects of this until everyone has cooled back down. That
you should not forward private correspondence to public mailing means that you should not air your angry words in public
lists or aliases. What people say one-to-one is often much less and you should not forward private correspondence to
sugar-coated than what they would say in public, and such public mailing lists or aliases. What people say
communications therefore have no place there - they only serve to one-to-one is often much less sugar-coated than what they
inflame an already bad situation. If the person sending you a would say in public, and such communications therefore
flame-o-gram at least had the grace to send it privately, then have no place there - they only serve to inflame an
have the grace to keep it private yourself. If you feel you are already bad situation. If the person sending you a
being unfairly treated by another developer, and it is causing you flame-o-gram at least had the grace to send it privately,
anguish, bring the matter up with core rather than taking it then have the grace to keep it private yourself. If you
public. We will do our best to play peace makers and get things feel you are being unfairly treated by another developer,
back to sanity. In cases where the dispute involves a change to and it is causing you anguish, bring the matter up with
the codebase and the participants do not appear to be reaching an core rather than taking it public. We will do our best to
amicable agreement, core may appoint a mutually-agreeable 3rd play peace makers and get things back to sanity. In cases
party to resolve the dispute. All parties involved must then 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 must then
agree to be bound by the decision reached by this 3rd agree to be bound by the decision reached by this 3rd
party.</para> party.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the <literal>committers</literal> mailing list <para>Respect all code freezes and read the
on a timely basis so you know when they are.</para> <literal>committers</literal> mailing list on a timely
basis so you know when they are.</para>
<para>Committing changes during a code freeze is a really big <para>Committing changes during a code freeze is a really
mistake and committers are expected to keep up-to-date on what's big mistake and committers are expected to keep up-to-date
going on before jumping in after a long absence and committing 10 on what's going on before jumping in after a long absence
megabytes worth of accumulated stuff. People who abuse this on a and committing 10 megabytes worth of accumulated stuff.
regular basis will have their commit privileges suspended until People who abuse this on a regular basis will have their
they get back from the FreeBSD Happy Reeducation Camp we run in commit privileges suspended until they get back from the
Greenland.</para> FreeBSD Happy Reeducation Camp we run in Greenland.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>When in doubt on any procedure, ask first!</para> <para>When in doubt on any procedure, ask first!</para>
<para>Many mistakes are made because someone is in a hurry and <para>Many mistakes are made because someone is in a hurry
just assumes they know the right way of doing something. If and just assumes they know the right way of doing
you have not done it before, chances are good that you do not something. If you have not done it before, chances are
actually know the way we do things and really need to ask first or good that you do not actually know the way we do things
you are going to completely embarrass yourself in public. There's and really need to ask first or you are going to
no shame in asking <quote>how in the heck do I do this?</quote> completely embarrass yourself in public. There's no shame
We already know you are an intelligent person; otherwise, you would not be a in asking <quote>how in the heck do I do this?</quote> We
committer.</para> already know you are an intelligent person; otherwise, you
would not be a committer.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Test your changes before committing them.</para> <para>Test your changes before committing them.</para>
<para>This may sound obvious, but if it really were so obvious then <para>This may sound obvious, but if it really were so
we probably wouldn't see so many cases of people clearly not doing obvious then we probably wouldn't see so many cases of
this. If your changes are to the kernel, make sure you can still people clearly not doing this. If your changes are to the
compile both GENERIC and LINT. If your changes are anywhere else, kernel, make sure you can still compile both GENERIC and
make sure you can still make world. If your changes are to a LINT. If your changes are anywhere else, make sure you
branch, make sure your testing occurs with a machine which is can still make world. If your changes are to a branch,
running that code. If you have a change which also may break make sure your testing occurs with a machine which is
another architecture, be sure and test on all supported running that code. If you have a change which also may
architectures. Currently, this is only the x86 and the alpha so break another architecture, be sure and test on all
it's pretty easy to do. If you need to test on the AXP, your supported architectures. Currently, this is only the x86
account on <hostid role="fqdn">beast.FreeBSD.org</hostid> will let and the alpha so it's pretty easy to do. If you need to
you compile and test alpha binaries/kernels/etc. As other test on the AXP, your account on <hostid
architectures are added to the FreeBSD supported platforms list, role="fqdn">beast.FreeBSD.org</hostid> will let you
the appropriate shared testing resources will be made compile and test alpha binaries/kernels/etc. As other
available.</para> architectures are added to the FreeBSD supported platforms
list, the appropriate shared testing resources will be
made available.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</sect2> </sect2>
@ -772,26 +822,27 @@
<sect2> <sect2>
<title>Other Suggestions</title> <title>Other Suggestions</title>
<para>When committing documentation changes, use a <para>When committing documentation changes, use a spell checker
spell checker before committing. :) For all SGML docs, you should before committing. :) For all SGML docs, you should also
also verify that your formatting directives are correct by running verify that your formatting directives are correct by running
<command>make lint</command>.</para> <command>make lint</command>.</para>
<para>For all on-line manual pages, run <command>manck</command> (from ports) over the <para>For all on-line manual pages, run <command>manck</command>
man page to verify the all of the cross references and file references (from ports) over the man page to verify the all of the cross
are correct and that the man page has all of the appropriate references and file references are correct and that the man
<makevar>MLINK</makevar>s installed.</para> page has all of the appropriate <makevar>MLINK</makevar>s
installed.</para>
<para>Do not mix style fixes with new functionality. A style <para>Do not mix style fixes with new functionality. A style
fix is any change which does not modify the functionality of fix is any change which does not modify the functionality of
the code. Mixing the changes ofucsates the functionality the code. Mixing the changes ofucsates the functionality
change when using <command>cvs diff</command>, which can hide change when using <command>cvs diff</command>, which can hide
any new bugs. Do not any new bugs. Do not include whitespace changes with content
include whitespace changes with content changes in commits to changes in commits to <filename>doc/</filename> or
<filename>doc/</filename> or <filename>www/</filename>. The extra clutter in the diffs <filename>www/</filename>. The extra clutter in the diffs
makes the translators' job much more difficult. Instead, make any makes the translators' job much more difficult. Instead, make
style or whitespace changes in seperate commits that are clearly any style or whitespace changes in seperate commits that are
labeled as such in the commit message.</para> clearly labeled as such in the commit message.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -815,9 +866,10 @@
<command>easy-import</command> script on <command>easy-import</command> script on
<hostid>freefall</hostid>. It will ask you some <hostid>freefall</hostid>. It will ask you some
questions and import the port in the directory you questions and import the port in the directory you
specify. It will also add an entry to the <filename>CVSROOT/modules</filename> specify. It will also add an entry to the
file. It was written by &a.joerg; so please send mail <filename>CVSROOT/modules</filename> file. It was
to him if you have questions about written by &a.joerg; so please send mail to him if you
have questions about
<command>easy-import</command>.</para> <command>easy-import</command>.</para>
<para>One thing it will not do for you is add the port to <para>One thing it will not do for you is add the port to
@ -857,8 +909,8 @@
<para>If the port came from a submitter who has not <para>If the port came from a submitter who has not
contributed to the project before, add that person's contributed to the project before, add that person's
name to the Handbook's name to the Handbook's <citetitle
<citetitle pubwork="section">Additional Contributors</citetitle> pubwork="section">Additional Contributors</citetitle>
section.</para> section.</para>
<para>Close the PR if the port came in as a PR. To close <para>Close the PR if the port came in as a PR. To close
@ -1024,17 +1076,19 @@
<answer> <answer>
<para>The ports manager will send out warning messages to <para>The ports manager will send out warning messages to
the <email>freebsd-ports@FreeBSD.org</email> and the <email>freebsd-ports@FreeBSD.org</email> and
<email>cvs-committers@FreeBSD.org</email> mailing lists announcing <email>cvs-committers@FreeBSD.org</email> mailing lists
the start of the impending release, usually two or three announcing the start of the impending release, usually
weeks in advance. The exact starting time will not be two or three weeks in advance. The exact starting time
determined until a few days before the actual release. will not be determined until a few days before the
This is because the ports freeze has to be synchronized actual release. This is because the ports freeze has to
with the release, and it is usually not known until then be synchronized with the release, and it is usually not
when exactly the release will be rolled.</para> known until then when exactly the release will be
rolled.</para>
<para>When the freeze starts, there will be another <para>When the freeze starts, there will be another
announcement to the <email>cvs-committers@FreeBSD.org</email> announcement to the
list, of course.</para> <email>cvs-committers@FreeBSD.org</email> list, of
course.</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -1147,14 +1201,16 @@
</question> </question>
<answer> <answer>
<para>The RCS file format is quite braindead and certain operations <para>The RCS file format is quite braindead and certain
to achieve things for CVS are hideously expensive for the operations to achieve things for CVS are hideously
repository. Making changes to files on a vendor branch, thereby expensive for the repository. Making changes to files on
pulling the file off that branch, is one example of this.</para> a vendor branch, thereby pulling the file off that branch,
is one example of this.</para>
<para>Suppose you have a file which was first imported on a vendor <para>Suppose you have a file which was first imported on a
branch, and was then re-imported three times (still on the vendor vendor branch, and was then re-imported three times (still
branch) as the vendor makes updates to the file.</para> on the vendor branch) as the vendor makes updates to the
file.</para>
<segmentedlist> <segmentedlist>
<seglistitem> <seglistitem>
@ -1178,21 +1234,25 @@
</seglistitem> </seglistitem>
</segmentedlist> </segmentedlist>
<para>Now suppose that one of the FreeBSD committers makes a one <para>Now suppose that one of the FreeBSD committers makes a
line change to this file, causing it to go to version 1.2. This one line change to this file, causing it to go to version
causes it to leave the branch, resulting in 4,001 lines being added 1.2. This causes it to leave the branch, resulting in
to the file's history, and 2,001 lines being deleted.</para> 4,001 lines being added to the file's history, and 2,001
lines being deleted.</para>
<para>This is because the 1.2 delta is stored relative to 1.1.1.1, <para>This is because the 1.2 delta is stored relative to
<emphasis>not</emphasis> 1.1.1.4, and so the entire vendor history 1.1.1.1, <emphasis>not</emphasis> 1.1.1.4, and so the
is duplicated in the 1.2 delta. Now, repeat this for 2000 files entire vendor history is duplicated in the 1.2 delta.
in a large directory, it adds up a lot.</para> Now, repeat this for 2000 files in a large directory, it
adds up a lot.</para>
<para><emphasis>This</emphasis> is why we have such <quote>hands <para><emphasis>This</emphasis> is why we have such
off</quote> policies for <filename>src/contrib</filename> and other things that track <quote>hands off</quote> policies for
the vendor releases. This is why <quote>typo fixes</quote> in man <filename>src/contrib</filename> and other things that
pages and spelling <quote>corrections</quote> are so strongly track the vendor releases. This is why <quote>typo
discouraged for vendor code.</para> fixes</quote> in man pages and spelling
<quote>corrections</quote> are so strongly discouraged for
vendor code.</para>
</answer> </answer>
</qandaentry> </qandaentry>
</qandaset> </qandaset>

652
en_US.ISO_8859-1/articles/committers-guide/article.sgml
View file

@ -185,10 +185,13 @@
(where <replaceable>user</replaceable> is your username) file (where <replaceable>user</replaceable> is your username) file
containing the e-mail address where you want mail addressed containing the e-mail address where you want mail addressed
to <replaceable>yourusername</replaceable>@FreeBSD.org to <replaceable>yourusername</replaceable>@FreeBSD.org
to be forwarded. This includes all of the commit messages as well as any other mail addressed to <email>cvs-committers@FreeBSD.org</email>. Really large mailboxes which have taken up to be forwarded. This includes all of the commit messages as
permanent residence on <hostid>hub</hostid> often get well as any other mail addressed to
<quote>accidently</quote> truncated without warning, so forward <email>cvs-committers@FreeBSD.org</email>. Really large
it or read it and you will not lose it.</para> mailboxes which have taken up permanent residence on
<hostid>hub</hostid> often get <quote>accidently</quote>
truncated without warning, so forward it or read it and you will
not lose it.</para>
<para>All new committers also have a mentor assigned to them for <para>All new committers also have a mentor assigned to them for
the first few months. Your mentor is more or less responsible for the first few months. Your mentor is more or less responsible for
@ -216,15 +219,20 @@
areas, to our shame), the same applies. If, however, you are areas, to our shame), the same applies. If, however, you are
about to modify something which is clearly being actively about to modify something which is clearly being actively
maintained by someone else (and it is only by watching the maintained by someone else (and it is only by watching the
<literal>cvs-committers</literal> mailing list that you can really get <literal>cvs-committers</literal> mailing list that you can
a feel for just what is and is not) then consider sending the really get a feel for just what is and is not) then consider
change to them instead, just as you would have before becoming a sending the change to them instead, just as you would have
committer. For ports, you should contact the listed before becoming a committer. For ports, you should contact the
<makevar>MAINTAINER</makevar> in the listed <makevar>MAINTAINER</makevar> in the
<filename>Makefile</filename>. For other parts of the <filename>Makefile</filename>. For other parts of the
repository, if you are unsure who the active maintainer might repository, if you are unsure who the active maintainer might
be, it may help to scan the output of <command>cvs log</command> be, it may help to scan the output of <command>cvs log</command>
to see who has committed changes in the past. &a.fenner; has written a nice shell script that can help determine who the active maintainer might be. It lists each person who has committed to a given file along with the number of commits each person has made. It can be found on <hostid>freefall</hostid> at <filename>~fenner/bin/whodid</filename>. If your queries go to see who has committed changes in the past. &a.fenner; has
written a nice shell script that can help determine who the
active maintainer might be. It lists each person who has
committed to a given file along with the number of commits each
person has made. It can be found on <hostid>freefall</hostid>
at <filename>~fenner/bin/whodid</filename>. If your queries go
unanswered or the committer otherwise indicates a lack of unanswered or the committer otherwise indicates a lack of
proprietary interest in the area affected, go ahead and commit proprietary interest in the area affected, go ahead and commit
it.</para> it.</para>
@ -289,10 +297,11 @@
<term>&a.asami;</term> <term>&a.asami;</term>
<listitem> <listitem>
<para>Satoshi is the Ports Wraith, meaning that he has ultimate <para>Satoshi is the Ports Wraith, meaning that he has
authority over any modifications to the ports collection or ultimate authority over any modifications to the ports
the ports skeleton makefiles. He is also the one responsible for collection or the ports skeleton makefiles. He is also
administering code freezes before the releases.</para> the one responsible for administering code freezes before
the releases.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -300,9 +309,9 @@
<term>&a.bde;</term> <term>&a.bde;</term>
<listitem> <listitem>
<para>Bruce is the Obersturmbahnfuhrer of the Style Police. When you <para>Bruce is the Obersturmbahnfuhrer of the Style Police.
do a commit that could have been done better, Bruce will When you do a commit that could have been done better,
be there to tell you. Be thankful that someone Bruce will be there to tell you. Be thankful that someone
is.</para> is.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -311,14 +320,13 @@
<term>&a.dg;</term> <term>&a.dg;</term>
<listitem> <listitem>
<para>David is our principal architect and overseer of the VM <para>David is our principal architect and overseer of the
system. If you have a VM system change in mind, VM system. If you have a VM system change in mind,
coordinate it with David. Should you become locked in a coordinate it with David. Should you become locked in a
bitter, intractable dispute with some other committer over bitter, intractable dispute with some other committer over
a proposed change (which does not happen very often, a proposed change (which does not happen very often,
thankfully) then an appeal to David to put on his P.A. hat thankfully) then an appeal to David to put on his P.A. hat
and make a final decision might be and make a final decision might be necessary.</para>
necessary.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -399,14 +407,15 @@
</step> </step>
<step> <step>
<para>If you do not wish to to type your password in every time <para>If you do not wish to to type your password in every
you use &man.ssh.1;, and you use RSA keys to authenticate, time you use &man.ssh.1;, and you use RSA keys to
&man.ssh-agent.1; is there for your convenience. If authenticate, &man.ssh-agent.1; is there for your
you want to use &man.ssh-agent.1;, make sure that you run it convenience. If you want to use &man.ssh-agent.1;, make
before running other applications. X users, for example, sure that you run it before running other applications. X
usually do this from their <filename>.xsession</filename> or users, for example, usually do this from their
<filename>.xinitrc</filename> file. <filename>.xsession</filename> or
See &man.ssh-agent.1; for details.</para> <filename>.xinitrc</filename> file. See &man.ssh-agent.1;
for details.</para>
</step> </step>
<step> <step>
@ -453,47 +462,54 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Discuss any significant change <emphasis>before</emphasis> <para>Discuss any significant change
committing.</para> <emphasis>before</emphasis> committing.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect existing maintainers if listed in the <para>Respect existing maintainers if listed in the
(<makevar>MAINTAINER</makevar> field in (<makevar>MAINTAINER</makevar> field in
<filename>Makefile</filename> or in the <filename>MAINTAINER</filename> <filename>Makefile</filename> or in the
file in the top-level directory).</para> <filename>MAINTAINER</filename> file in the top-level
directory).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Never touch the repository directly. Ask a Repomeister.</para> <para>Never touch the repository directly. Ask a
Repomeister.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Any disputed change must be backed out pending resolution of <para>Any disputed change must be backed out pending
the dispute if requested by a maintainer or the Principal resolution of the dispute if requested by a maintainer or
Architect. Security related changes may override a maintainer's the Principal Architect. Security related changes may
wishes at the Security Officer's discretion.</para> override a maintainer's wishes at the Security Officer's
discretion.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically <para>Changes go to <literal>-CURRENT</literal> before
permitted by the release engineer or unless they're not applicable <literal>-STABLE</literal> unless specifically permitted by
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is the release engineer or unless they're not applicable to
applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least 3 <literal>-CURRENT</literal>. Any non-trivial or non-urgent
days before merging so that it can be given sufficient testing. The change which is applicable should also be allowed to sit in
release engineer has the same authority over the <literal>-STABLE</literal> branch as <literal>-CURRENT</literal> for at least 3 days before
outlined for the Principal Architect in rule #5.</para> merging so that it can be given sufficient testing. The
release engineer has the same authority over the
<literal>-STABLE</literal> branch as outlined for the
Principal Architect in rule #5.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Don't fight in public with other committers; it looks bad. If <para>Don't fight in public with other committers; it looks
you must <quote>strongly disagree</quote> about something, do so only in bad. If you must <quote>strongly disagree</quote> about
private.</para> something, do so only in private.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the <literal>committers</literal> mailing list on <para>Respect all code freezes and read the
a timely basis so you know when a code freeze is in effect.</para> <literal>committers</literal> mailing list on a timely basis
so you know when a code freeze is in effect.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -505,40 +521,45 @@
</listitem> </listitem>
</orderedlist> </orderedlist>
<para>As noted, breaking some of these rules can be grounds for suspension <para>As noted, breaking some of these rules can be grounds for
or, upon repeated offense, permanent removal of commit privileges. suspension or, upon repeated offense, permanent removal of
Three or more members of core, or the Principal Architect and another commit privileges. Three or more members of core, or the
member of core acting in unison, have the power to temporarily suspend Principal Architect and another member of core acting in unison,
commit privileges until <literal>-core</literal> as a whole has the chance to review the have the power to temporarily suspend commit privileges until
issue. In case of an <quote>emergency</quote> (a committer doing damage to the <literal>-core</literal> as a whole has the chance to review the
repository), a temporary suspension may also be done by the repository issue. In case of an <quote>emergency</quote> (a committer
meisters or any other member of core who may happen to be awake at the doing damage to the repository), a temporary suspension may also
time. Only core as a whole has the authority to suspend commit be done by the repository meisters or any other member of core
privileges for any significant length of time or to remove them who may happen to be awake at the time. Only core as a whole
permanently, the latter generally only being done after consultation has the authority to suspend commit privileges for any
with committers. This rule does not exist to set core up as a bunch of significant length of time or to remove them permanently, the
cruel dictators who can dispose of committers as casually as empty soda latter generally only being done after consultation with
cans, but to give the project a kind of safety fuse. If someone is committers. This rule does not exist to set core up as a bunch
seriously out of control, it's important to be able to deal with this of cruel dictators who can dispose of committers as casually as
immediately rather than be paralyzed by debate. In all cases, a empty soda cans, but to give the project a kind of safety fuse.
committer whose privileges are suspended or revoked is entitled to a If someone is seriously out of control, it's important to be
<quote>hearing</quote>, the total duration of the suspension being able to deal with this immediately rather than be paralyzed by
determined at that time. A committer whose privileges are suspended may debate. In all cases, a committer whose privileges are
also request a review of the decision after 30 days and every 30 days suspended or revoked is entitled to a <quote>hearing</quote>,
thereafter (unless the total suspension period is less than 30 days). A the total duration of the suspension being determined at that
committer whose privileges have been revoked entirely may request a time. A committer whose privileges are suspended may also
review after a period of 6 months have elapsed. This review policy is request a review of the decision after 30 days and every 30 days
<emphasis>strictly informal</emphasis> and, in all cases, core reserves thereafter (unless the total suspension period is less than 30
the right to either act on or disregard requests for review if they feel days). A committer whose privileges have been revoked entirely
their original decision to be the right one.</para> 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 <para>In all other aspects of project operation, core is a subset
committers and is bound by the <emphasis>same rules</emphasis>. Just of committers and is bound by the <emphasis>same
because someone is in core doesn't mean that they have special rules</emphasis>. Just because someone is in core doesn't mean
dispensation to step outside of any of the lines painted here; core's that they have special dispensation to step outside of any of
<quote>special powers</quote> only kick in when it acts as a group, not the lines painted here; core's <quote>special powers</quote>
on an individual basis. As individuals, we are all committers first and only kick in when it acts as a group, not on an individual
core second.</para> basis. As individuals, we are all committers first and core
second.</para>
<sect2> <sect2>
<title>Details</title> <title>Details</title>
@ -547,55 +568,61 @@
<listitem> <listitem>
<para>Respect other committers.</para> <para>Respect other committers.</para>
<para>This means that you need to treat other committers as the <para>This means that you need to treat other committers as
peer-group developers that they are. Despite our occasional the peer-group developers that they are. Despite our
attempts to prove the contrary, one doesn't get into committers by occasional attempts to prove the contrary, one doesn't get
being stupid and nothing rankles more than being treated that way into committers by being stupid and nothing rankles more
by one of your peers. Whether we always feel respect for one than being treated that way by one of your peers. Whether
another or not (and everyone has off days), we still have to we always feel respect for one another or not (and
<emphasis>treat</emphasis> other committers with respect at all everyone has off days), we still have to
times or the whole team structure rapidly breaks down.</para> <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 <para>Being able to work together long term is this project's
greatest asset, one far more important than any set of changes to greatest asset, one far more important than any set of
the code, and turning arguments about code into issues that affect changes to the code, and turning arguments about code into
our long-term ability to work harmoniously together is just not issues that affect our long-term ability to work
worth the trade-off by any conceivable stretch of the harmoniously together is just not worth the trade-off by
imagination.</para> any conceivable stretch of the imagination.</para>
<para>To comply with this rule, don't send email when you're angry <para>To comply with this rule, don't send email when you're
or otherwise behave in a manner which is likely to strike others angry or otherwise behave in a manner which is likely to
as needlessly confrontational. First calm down, then think about strike others as needlessly confrontational. First calm
how to communicate in the most effective fashion for convincing down, then think about how to communicate in the most
the other person(s) that your side of the argument is correct, effective fashion for convincing the other person(s) that
don't just blow off some steam so you can feel better in the short your side of the argument is correct, don't just blow off
term at the cost of a long-term flame war. Not only is this very some steam so you can feel better in the short term at the
bad <quote>energy economics</quote>, but repeated displays of cost of a long-term flame war. Not only is this very bad
public aggression which impair our ability to work well together <quote>energy economics</quote>, but repeated displays of
will be dealt with severely by the project leadership and may public aggression which impair our ability to work well
result in suspension or termination of your commit privileges. together will be dealt with severely by the project
That's never an option which the project's leadership enjoys in leadership and may result in suspension or termination of
the slightest, but unity comes first. No amount of code or good your commit privileges. That's never an option which the
advice is worth trading that away.</para> 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>
<listitem> <listitem>
<para>Discuss any significant change <emphasis>before</emphasis> <para>Discuss any significant change
committing.</para> <emphasis>before</emphasis> committing.</para>
<para>The CVS repository is not where changes should be initially <para>The CVS repository is not where changes should be
submitted for correctness or argued over, that should happen first initially submitted for correctness or argued over, that
in the mailing lists and then committed only once something should happen first in the mailing lists and then
resembling consensus has been reached. This doesn't mean that you committed only once something resembling consensus has
have to ask permission before correcting every obvious syntax been reached. This doesn't mean that you have to ask
error or man page misspelling, simply that you should try to permission before correcting every obvious syntax error or
develop a feel for when a proposed change isn't quite such a man page misspelling, simply that you should try to
no-brainer and requires some feedback first. People really don't develop a feel for when a proposed change isn't quite such
mind sweeping changes if the result is something clearly better a no-brainer and requires some feedback first. People
than what they had before, they just don't like being really don't mind sweeping changes if the result is
<emphasis>surprised</emphasis> by those changes. The very best something clearly better than what they had before, they
way of making sure that you're on the right track is to have your just don't like being <emphasis>surprised</emphasis> by
code reviewed by one or more other committers.</para> 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> <para>When in doubt, ask for review!</para>
</listitem> </listitem>
@ -603,168 +630,191 @@
<listitem> <listitem>
<para>Respect existing maintainers if listed.</para> <para>Respect existing maintainers if listed.</para>
<para>Many parts of FreeBSD aren't <quote>owned</quote> in the sense <para>Many parts of FreeBSD aren't <quote>owned</quote> in
that any specific individual will jump up and yell if you commit a the sense that any specific individual will jump up and
change to <quote>their</quote> area, but it still pays to check yell if you commit a change to <quote>their</quote> area,
first. One convention we use is to put a maintainer line in the but it still pays to check first. One convention we use
<filename>Makefile</filename> for any package or subtree which is is to put a maintainer line in the
being actively maintained by one or more people; see <ulink <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> 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 for documentation on this. Where sections of code have
maintainers, commits to affected areas by one maintainer need to several maintainers, commits to affected areas by one
be reviewed by at least one other maintainer. In cases where the maintainer need to be reviewed by at least one other
<quote>maintainer-ship</quote> of something isn't clear, you can also look at maintainer. In cases where the
the CVS logs for the file(s) in question and see if someone has <quote>maintainer-ship</quote> of something isn't clear,
been working recently or predominantly in that area.</para> 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 <para>Other areas of FreeBSD fall under the control of
manages an overall category of FreeBSD evolution, such as someone who manages an overall category of FreeBSD
internationalization or networking. See evolution, such as internationalization or networking.
<ulink See <ulink url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.FreeBSD.org/handbook/staff-who.html</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> for more information on this.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Never touch the repository directly. Ask a <para>Never touch the repository directly. Ask a
Repomeister.</para> Repomeister.</para>
<para>This is pretty clear - you're not allowed to make direct <para>This is pretty clear - you're not allowed to make
modifications to the CVS repository, period. In case of direct modifications to the CVS repository, period. In
difficulty, ask one of the repository meisters by sending mail to case of difficulty, ask one of the repository meisters by
<email>cvs@FreeBSD.org</email> and simply wait for them to fix the sending mail to <email>cvs@FreeBSD.org</email> and simply
problem and get back to you. Do not attempt to fix the problem wait for them to fix the problem and get back to you. Do
yourself!</para> not attempt to fix the problem yourself!</para>
<para>If you're thinking about putting down a tag or doing a new <para>If you're thinking about putting down a tag or doing a
import of code on a vendor branch, you might also find it useful new import of code on a vendor branch, you might also find
to ask for advice first. A lot of people get this wrong the first it useful to ask for advice first. A lot of people get
few times and the consequences are expensive in terms of files this wrong the first few times and the consequences are
touched and angry CVSup/CTM folks who are suddenly getting a lot expensive in terms of files touched and angry CVSup/CTM
of changes sent over unnecessarily.</para> folks who are suddenly getting a lot of changes sent over
unnecessarily.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Any disputed change must be backed out pending resolution of <para>Any disputed change must be backed out pending
the dispute if requested by a maintainer or the Principal resolution of the dispute if requested by a maintainer or
Architect. Security related changes may override a maintainer's the Principal Architect. Security related changes may
wishes at the Security Officer's discretion.</para> 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 <para>This may be hard to swallow in times of conflict (when
side is convinced that they're in the right, of course) but CVS each side is convinced that they're in the right, of
makes it unnecessary to have an ongoing dispute raging when it's course) but CVS makes it unnecessary to have an ongoing
far easier to simply reverse the disputed change, get everyone dispute raging when it's far easier to simply reverse the
calmed down again and then try and figure out how best to proceed. disputed change, get everyone calmed down again and then
If the change turns out to be the best thing after all, it can be try and figure out how best to proceed. If the change
easily brought back. If it turns out not to be, then the users turns out to be the best thing after all, it can be easily
didn't have to live with the bogus change in the tree while brought back. If it turns out not to be, then the users
everyone was busily debating its merits. People very very rarely didn't have to live with the bogus change in the tree
call for back-outs in the repository since discussion generally while everyone was busily debating its merits. People
exposes bad or controversial changes before the commit even very very rarely call for back-outs in the repository
happens, but on such rare occasions the back-out should be done since discussion generally exposes bad or controversial
without argument so that we can get immediately on to the topic of changes before the commit even happens, but on such rare
figuring out whether it was bogus or not.</para> 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>
<listitem> <listitem>
<para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically <para>Changes go to <literal>-CURRENT</literal> before
permitted by the release engineer or unless they're not applicable <literal>-STABLE</literal> unless specifically permitted
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is by the release engineer or unless they're not applicable
applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least to <literal>-CURRENT</literal>. Any non-trivial or
3 days before merging so that it can be given sufficient testing. non-urgent change which is applicable should also be
The release engineer has the same authority over the <literal>-STABLE</literal> allowed to sit in <literal>-CURRENT</literal> for at least
branch as outlined in rule #5.</para> 3 days before merging so that it can be given sufficient
testing. The release engineer has the same authority over
the <literal>-STABLE</literal> branch as outlined in rule
#5.</para>
<para>This is another <quote>don't argue about it</quote> issue since it's the <para>This is another <quote>don't argue about it</quote>
release engineer who is ultimately responsible (and gets beaten issue since it's the release engineer who is ultimately
up) if a change turns out to be bad. Please respect this and give responsible (and gets beaten up) if a change turns out to
the release engineer your full cooperation when it comes to the be bad. Please respect this and give the release engineer
<literal>-STABLE</literal> branch. The management of <literal>-STABLE</literal> may frequently seem to your full cooperation when it comes to the
be overly conservative to the casual observer, but also bear in <literal>-STABLE</literal> branch. The management of
mind the fact that conservatism is supposed to be the hallmark of <literal>-STABLE</literal> may frequently seem to be
<literal>-STABLE</literal> and different rules apply there than in <literal>-CURRENT</literal>. There's overly conservative to the casual observer, but also bear
also really no point in having <literal>-CURRENT</literal> be a testing ground if in mind the fact that conservatism is supposed to be the
changes are merged over to <literal>-STABLE</literal> immediately. Changes need hallmark of <literal>-STABLE</literal> and different rules
a chance to be tested by the <literal>-CURRENT</literal> developers, so allow some apply there than in <literal>-CURRENT</literal>. There's
time to elapse before merging unless the <literal>-STABLE</literal> fix is critical, also really no point in having <literal>-CURRENT</literal>
be a testing ground if changes are merged over to
<literal>-STABLE</literal> immediately. Changes need a
chance to be tested by the <literal>-CURRENT</literal>
developers, so allow some time to elapse before merging
unless the <literal>-STABLE</literal> fix is critical,
time sensitive or so obvious as to make further testing time sensitive or so obvious as to make further testing
unnecessary (spelling fixes to manpages, obvious bug/typo fixes, unnecessary (spelling fixes to manpages, obvious bug/typo
etc.) In other words, apply common sense.</para> fixes, etc.) In other words, apply common sense.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Don't fight in public with other committers; it looks bad. If <para>Don't fight in public with other committers; it looks
you must <quote>strongly disagree</quote> about something, do so bad. If you must <quote>strongly disagree</quote> about
only in private.</para> something, do so only in private.</para>
<para>This project has a public image to uphold and that image is <para>This project has a public image to uphold and that
very important to all of us, especially if we are to continue to image is very important to all of us, especially if we are
attract new members. There will be occasions when, despite to continue to attract new members. There will be
everyone's very best attempts at self-control, tempers are lost occasions when, despite everyone's very best attempts at
and angry words are exchanged, and the best we can do is try and self-control, tempers are lost and angry words are
minimize the effects of this until everyone has cooled back down. exchanged, and the best we can do is try and minimize the
That means that you should not air your angry words in public and effects of this until everyone has cooled back down. That
you should not forward private correspondence to public mailing means that you should not air your angry words in public
lists or aliases. What people say one-to-one is often much less and you should not forward private correspondence to
sugar-coated than what they would say in public, and such public mailing lists or aliases. What people say
communications therefore have no place there - they only serve to one-to-one is often much less sugar-coated than what they
inflame an already bad situation. If the person sending you a would say in public, and such communications therefore
flame-o-gram at least had the grace to send it privately, then have no place there - they only serve to inflame an
have the grace to keep it private yourself. If you feel you are already bad situation. If the person sending you a
being unfairly treated by another developer, and it is causing you flame-o-gram at least had the grace to send it privately,
anguish, bring the matter up with core rather than taking it then have the grace to keep it private yourself. If you
public. We will do our best to play peace makers and get things feel you are being unfairly treated by another developer,
back to sanity. In cases where the dispute involves a change to and it is causing you anguish, bring the matter up with
the codebase and the participants do not appear to be reaching an core rather than taking it public. We will do our best to
amicable agreement, core may appoint a mutually-agreeable 3rd play peace makers and get things back to sanity. In cases
party to resolve the dispute. All parties involved must then 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 must then
agree to be bound by the decision reached by this 3rd agree to be bound by the decision reached by this 3rd
party.</para> party.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the <literal>committers</literal> mailing list <para>Respect all code freezes and read the
on a timely basis so you know when they are.</para> <literal>committers</literal> mailing list on a timely
basis so you know when they are.</para>
<para>Committing changes during a code freeze is a really big <para>Committing changes during a code freeze is a really
mistake and committers are expected to keep up-to-date on what's big mistake and committers are expected to keep up-to-date
going on before jumping in after a long absence and committing 10 on what's going on before jumping in after a long absence
megabytes worth of accumulated stuff. People who abuse this on a and committing 10 megabytes worth of accumulated stuff.
regular basis will have their commit privileges suspended until People who abuse this on a regular basis will have their
they get back from the FreeBSD Happy Reeducation Camp we run in commit privileges suspended until they get back from the
Greenland.</para> FreeBSD Happy Reeducation Camp we run in Greenland.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>When in doubt on any procedure, ask first!</para> <para>When in doubt on any procedure, ask first!</para>
<para>Many mistakes are made because someone is in a hurry and <para>Many mistakes are made because someone is in a hurry
just assumes they know the right way of doing something. If and just assumes they know the right way of doing
you have not done it before, chances are good that you do not something. If you have not done it before, chances are
actually know the way we do things and really need to ask first or good that you do not actually know the way we do things
you are going to completely embarrass yourself in public. There's and really need to ask first or you are going to
no shame in asking <quote>how in the heck do I do this?</quote> completely embarrass yourself in public. There's no shame
We already know you are an intelligent person; otherwise, you would not be a in asking <quote>how in the heck do I do this?</quote> We
committer.</para> already know you are an intelligent person; otherwise, you
would not be a committer.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Test your changes before committing them.</para> <para>Test your changes before committing them.</para>
<para>This may sound obvious, but if it really were so obvious then <para>This may sound obvious, but if it really were so
we probably wouldn't see so many cases of people clearly not doing obvious then we probably wouldn't see so many cases of
this. If your changes are to the kernel, make sure you can still people clearly not doing this. If your changes are to the
compile both GENERIC and LINT. If your changes are anywhere else, kernel, make sure you can still compile both GENERIC and
make sure you can still make world. If your changes are to a LINT. If your changes are anywhere else, make sure you
branch, make sure your testing occurs with a machine which is can still make world. If your changes are to a branch,
running that code. If you have a change which also may break make sure your testing occurs with a machine which is
another architecture, be sure and test on all supported running that code. If you have a change which also may
architectures. Currently, this is only the x86 and the alpha so break another architecture, be sure and test on all
it's pretty easy to do. If you need to test on the AXP, your supported architectures. Currently, this is only the x86
account on <hostid role="fqdn">beast.FreeBSD.org</hostid> will let and the alpha so it's pretty easy to do. If you need to
you compile and test alpha binaries/kernels/etc. As other test on the AXP, your account on <hostid
architectures are added to the FreeBSD supported platforms list, role="fqdn">beast.FreeBSD.org</hostid> will let you
the appropriate shared testing resources will be made compile and test alpha binaries/kernels/etc. As other
available.</para> architectures are added to the FreeBSD supported platforms
list, the appropriate shared testing resources will be
made available.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</sect2> </sect2>
@ -772,26 +822,27 @@
<sect2> <sect2>
<title>Other Suggestions</title> <title>Other Suggestions</title>
<para>When committing documentation changes, use a <para>When committing documentation changes, use a spell checker
spell checker before committing. :) For all SGML docs, you should before committing. :) For all SGML docs, you should also
also verify that your formatting directives are correct by running verify that your formatting directives are correct by running
<command>make lint</command>.</para> <command>make lint</command>.</para>
<para>For all on-line manual pages, run <command>manck</command> (from ports) over the <para>For all on-line manual pages, run <command>manck</command>
man page to verify the all of the cross references and file references (from ports) over the man page to verify the all of the cross
are correct and that the man page has all of the appropriate references and file references are correct and that the man
<makevar>MLINK</makevar>s installed.</para> page has all of the appropriate <makevar>MLINK</makevar>s
installed.</para>
<para>Do not mix style fixes with new functionality. A style <para>Do not mix style fixes with new functionality. A style
fix is any change which does not modify the functionality of fix is any change which does not modify the functionality of
the code. Mixing the changes ofucsates the functionality the code. Mixing the changes ofucsates the functionality
change when using <command>cvs diff</command>, which can hide change when using <command>cvs diff</command>, which can hide
any new bugs. Do not any new bugs. Do not include whitespace changes with content
include whitespace changes with content changes in commits to changes in commits to <filename>doc/</filename> or
<filename>doc/</filename> or <filename>www/</filename>. The extra clutter in the diffs <filename>www/</filename>. The extra clutter in the diffs
makes the translators' job much more difficult. Instead, make any makes the translators' job much more difficult. Instead, make
style or whitespace changes in seperate commits that are clearly any style or whitespace changes in seperate commits that are
labeled as such in the commit message.</para> clearly labeled as such in the commit message.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -815,9 +866,10 @@
<command>easy-import</command> script on <command>easy-import</command> script on
<hostid>freefall</hostid>. It will ask you some <hostid>freefall</hostid>. It will ask you some
questions and import the port in the directory you questions and import the port in the directory you
specify. It will also add an entry to the <filename>CVSROOT/modules</filename> specify. It will also add an entry to the
file. It was written by &a.joerg; so please send mail <filename>CVSROOT/modules</filename> file. It was
to him if you have questions about written by &a.joerg; so please send mail to him if you
have questions about
<command>easy-import</command>.</para> <command>easy-import</command>.</para>
<para>One thing it will not do for you is add the port to <para>One thing it will not do for you is add the port to
@ -857,8 +909,8 @@
<para>If the port came from a submitter who has not <para>If the port came from a submitter who has not
contributed to the project before, add that person's contributed to the project before, add that person's
name to the Handbook's name to the Handbook's <citetitle
<citetitle pubwork="section">Additional Contributors</citetitle> pubwork="section">Additional Contributors</citetitle>
section.</para> section.</para>
<para>Close the PR if the port came in as a PR. To close <para>Close the PR if the port came in as a PR. To close
@ -1024,17 +1076,19 @@
<answer> <answer>
<para>The ports manager will send out warning messages to <para>The ports manager will send out warning messages to
the <email>freebsd-ports@FreeBSD.org</email> and the <email>freebsd-ports@FreeBSD.org</email> and
<email>cvs-committers@FreeBSD.org</email> mailing lists announcing <email>cvs-committers@FreeBSD.org</email> mailing lists
the start of the impending release, usually two or three announcing the start of the impending release, usually
weeks in advance. The exact starting time will not be two or three weeks in advance. The exact starting time
determined until a few days before the actual release. will not be determined until a few days before the
This is because the ports freeze has to be synchronized actual release. This is because the ports freeze has to
with the release, and it is usually not known until then be synchronized with the release, and it is usually not
when exactly the release will be rolled.</para> known until then when exactly the release will be
rolled.</para>
<para>When the freeze starts, there will be another <para>When the freeze starts, there will be another
announcement to the <email>cvs-committers@FreeBSD.org</email> announcement to the
list, of course.</para> <email>cvs-committers@FreeBSD.org</email> list, of
course.</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -1147,14 +1201,16 @@
</question> </question>
<answer> <answer>
<para>The RCS file format is quite braindead and certain operations <para>The RCS file format is quite braindead and certain
to achieve things for CVS are hideously expensive for the operations to achieve things for CVS are hideously
repository. Making changes to files on a vendor branch, thereby expensive for the repository. Making changes to files on
pulling the file off that branch, is one example of this.</para> a vendor branch, thereby pulling the file off that branch,
is one example of this.</para>
<para>Suppose you have a file which was first imported on a vendor <para>Suppose you have a file which was first imported on a
branch, and was then re-imported three times (still on the vendor vendor branch, and was then re-imported three times (still
branch) as the vendor makes updates to the file.</para> on the vendor branch) as the vendor makes updates to the
file.</para>
<segmentedlist> <segmentedlist>
<seglistitem> <seglistitem>
@ -1178,21 +1234,25 @@
</seglistitem> </seglistitem>
</segmentedlist> </segmentedlist>
<para>Now suppose that one of the FreeBSD committers makes a one <para>Now suppose that one of the FreeBSD committers makes a
line change to this file, causing it to go to version 1.2. This one line change to this file, causing it to go to version
causes it to leave the branch, resulting in 4,001 lines being added 1.2. This causes it to leave the branch, resulting in
to the file's history, and 2,001 lines being deleted.</para> 4,001 lines being added to the file's history, and 2,001
lines being deleted.</para>
<para>This is because the 1.2 delta is stored relative to 1.1.1.1, <para>This is because the 1.2 delta is stored relative to
<emphasis>not</emphasis> 1.1.1.4, and so the entire vendor history 1.1.1.1, <emphasis>not</emphasis> 1.1.1.4, and so the
is duplicated in the 1.2 delta. Now, repeat this for 2000 files entire vendor history is duplicated in the 1.2 delta.
in a large directory, it adds up a lot.</para> Now, repeat this for 2000 files in a large directory, it
adds up a lot.</para>
<para><emphasis>This</emphasis> is why we have such <quote>hands <para><emphasis>This</emphasis> is why we have such
off</quote> policies for <filename>src/contrib</filename> and other things that track <quote>hands off</quote> policies for
the vendor releases. This is why <quote>typo fixes</quote> in man <filename>src/contrib</filename> and other things that
pages and spelling <quote>corrections</quote> are so strongly track the vendor releases. This is why <quote>typo
discouraged for vendor code.</para> fixes</quote> in man pages and spelling
<quote>corrections</quote> are so strongly discouraged for
vendor code.</para>
</answer> </answer>
</qandaentry> </qandaentry>
</qandaset> </qandaset>