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

Patch to the committers guide including several grammar fixes, markup

Browse source 
fixes, and re-wordings to try and make the text clearer. I also expanded
several contractions, mentioned Bill Fenner's whodid script, and added a
couple of clarifications.

Reviewed by:	obrien, nbm
Reviewed by:	Will Andrews <andrews@technologist.com>
This commit is contained in:
John Baldwin 2000-01-27 15:31:37 +00:00
parent f85a767c54
commit e49d537086
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=6442
2 changed files with 160 additions and 154 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -180,12 +180,12 @@
your way!</para> your way!</para>
<para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid> <para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid>
and create yourself a and create a
<filename>/var/forward/<replaceable>user</replaceable></filename> <filename>/var/forward/<replaceable>user</replaceable></filename>
(where <replaceable>user</replaceable> is your username) file (where <replaceable>user</replaceable> is your username) file
which contains your principal e-mail address where you want mail 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. Really large mailboxes which have taken up 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
permanent residence on <hostid>hub</hostid> often get permanent residence on <hostid>hub</hostid> often get
<quote>accidently</quote> truncated without warning, so forward <quote>accidently</quote> truncated without warning, so forward
it or read it and you will not lose it.</para> it or read it and you will not lose it.</para>
@ -216,7 +216,7 @@
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-all</literal> mailing list that you can really get <literal>cvs-committers</literal> mailing list that you can really get
a feel for just what is and is not) then consider sending the a feel for just what is and is not) then consider sending the
change to them instead, just as you would have before becoming a change to them instead, just as you would have before becoming a
committer. For ports, you should contact the listed committer. For ports, you should contact the listed
@ -224,7 +224,7 @@
<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. 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,9 +289,9 @@
<term>&a.asami;</term> <term>&a.asami;</term>
<listitem> <listitem>
<para>Is the portsmeister, meaning that he has ultimate <para>Satoshi is the Ports Wraith, meaning that he has ultimate
authority over any modifications to the ports collection or authority over any modifications to the ports collection or
ports make macro files. He is also the one responsible for the ports skeleton makefiles. He is also the one responsible for
administering code freezes before the releases.</para> administering code freezes before the releases.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -300,9 +300,9 @@
<term>&a.bde;</term> <term>&a.bde;</term>
<listitem> <listitem>
<para>Is Obersturmbahnfuhrer of the Style Police. When you <para>Bruce is the Obersturmbahnfuhrer of the Style Police. When you
do a commit that could have been done better, Bruce will do a commit that could have been done better, Bruce will
be there to note it to you. Be thankful that someone be there to tell you. Be thankful that someone
is.</para> is.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -311,13 +311,13 @@
<term>&a.dg;</term> <term>&a.dg;</term>
<listitem> <listitem>
<para>Is our principal architect and overseer of the VM <para>David is our principal architect and overseer of the VM
system. If you have a VM system change in mind, system. If you have a VM system change in mind,
coordinate it with David. Should you become locked in 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 can also occasionally be and make a final decision might be
necessary.</para> necessary.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -326,7 +326,7 @@
<term>&a.jkh;</term> <term>&a.jkh;</term>
<listitem> <listitem>
<para>Is the release engineer. He is responsible for <para>Jordan is the release engineer. He is responsible for
setting release deadlines and controlling the release setting release deadlines and controlling the release
process. During code freezes, he also has final authority process. During code freezes, he also has final authority
on all changes to the system for whichever branch is on all changes to the system for whichever branch is
@ -334,7 +334,7 @@
merged from <literal>-CURRENT</literal> to merged from <literal>-CURRENT</literal> to
<literal>-STABLE</literal> (whatever values those may have <literal>-STABLE</literal> (whatever values those may have
at any given time), he is also the one to talk to about at any given time), he is also the one to talk to about
it</para> it.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -354,10 +354,10 @@
<term>&a.steve;</term> <term>&a.steve;</term>
<listitem> <listitem>
<para>Steve is unofficial maintainer of <para>Steve is the unofficial maintainer of
<filename>/usr/src/bin</filename>. If you have something <filename>src/bin</filename>. If you have something
significant you'd like to do there, you should probably significant you'd like to do there, you should probably
coordinate it first with Steve. He's also Problem coordinate it with Steve first. He is also a Problem
Report-meister, along with &a.phk;.</para> Report-meister, along with &a.phk;.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -458,9 +458,9 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Respect existing maintainers if listed <para>Respect existing maintainers if listed in the
(<makevar>MAINTAINER</makevar> field in (<makevar>MAINTAINER</makevar> field in
<filename>Makefile</filename> or <filename>MAINTAINER</filename> <filename>Makefile</filename> or in the <filename>MAINTAINER</filename>
file in the top-level directory).</para> file in the top-level directory).</para>
</listitem> </listitem>
@ -476,23 +476,23 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Changes go to -current before -stable unless specifically <para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically
permitted by the release engineer or unless they're not applicable permitted by the release engineer or unless they're not applicable
to -current. Any non-trivial or non-urgent change which is to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
applicable should also be allowed to sit in -current for at least 3 applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least 3
days before merging so that it can be given sufficient testing. The days before merging so that it can be given sufficient testing. The
release engineer has the same authority over the -stable branch as release engineer has the same authority over the <literal>-STABLE</literal> branch as
outlined for the Principal Architect in rule #5.</para> 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 bad. If
you must "strongly disagree" about something, do so only in you must <quote>strongly disagree</quote> about something, do so only in
private.</para> private.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the committers mailing list on <para>Respect all code freezes and read the <literal>committers</literal> mailing list on
a timely basis so you know when a code freeze is in effect.</para> a timely basis so you know when a code freeze is in effect.</para>
</listitem> </listitem>
@ -510,7 +510,7 @@
Three or more members of core, or the Principal Architect and another Three or more members of core, or the Principal Architect and another
member of core acting in unison, have the power to temporarily suspend member of core acting in unison, have the power to temporarily suspend
commit privileges until <literal>-core</literal> as a whole has the chance to review the commit privileges until <literal>-core</literal> as a whole has the chance to review the
issue. In cases of <quote>emergency</quote> (a committer doing damage to the issue. In case of an <quote>emergency</quote> (a committer doing damage to the
repository), a temporary suspension may also be done by the repository 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 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 time. Only core as a whole has the authority to suspend commit
@ -522,7 +522,7 @@
seriously out of control, it's important to be able to deal with this 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 immediately rather than be paralyzed by debate. In all cases, a
committer whose privileges are suspended or revoked is entitled to a committer whose privileges are suspended or revoked is entitled to a
&ldquo;hearing&rdquo;, the total duration of the suspension being <quote>hearing</quote>, the total duration of the suspension being
determined at that time. A committer whose privileges are suspended may 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 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 thereafter (unless the total suspension period is less than 30 days). A
@ -536,7 +536,7 @@
committers and is bound by the <emphasis>same rules</emphasis>. Just committers and is bound by the <emphasis>same rules</emphasis>. Just
because someone is in core doesn't mean that they have special 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 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 <quote>special powers</quote> only kick in when it acts as a group, not
on an individual basis. As individuals, we are all committers first and on an individual basis. As individuals, we are all committers first and
core second.</para> core second.</para>
@ -570,7 +570,7 @@
the other person(s) that your side of the argument is correct, 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 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 term at the cost of a long-term flame war. Not only is this very
bad &ldquo;energy economics&rdquo;, but repeated displays of bad <quote>energy economics</quote>, but repeated displays of
public aggression which impair our ability to work well together public aggression which impair our ability to work well together
will be dealt with severely by the project leadership and may will be dealt with severely by the project leadership and may
result in suspension or termination of your commit privileges. result in suspension or termination of your commit privileges.
@ -603,9 +603,9 @@
<listitem> <listitem>
<para>Respect existing maintainers if listed.</para> <para>Respect existing maintainers if listed.</para>
<para>Many parts of FreeBSD aren't &ldquo;owned&rdquo; in the sense <para>Many parts of FreeBSD aren't <quote>owned</quote> in the sense
that any specific individual will jump up and yell if you commit a 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 change to <quote>their</quote> area, but it still pays to check
first. One convention we use is to put a maintainer line in the first. One convention we use is to put a maintainer line in the
<filename>Makefile</filename> for any package or subtree which is <filename>Makefile</filename> for any package or subtree which is
being actively maintained by one or more people; see <ulink being actively maintained by one or more people; see <ulink
@ -666,26 +666,26 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Changes go to -current before -stable unless specifically <para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically
permitted by the release engineer or unless they're not applicable permitted by the release engineer or unless they're not applicable
to -current. Any non-trivial or non-urgent change which is to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
applicable should also be allowed to sit in -current for at least applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least
3 days before merging so that it can be given sufficient testing. 3 days before merging so that it can be given sufficient testing.
The release engineer has the same authority over the -stable The release engineer has the same authority over the <literal>-STABLE</literal>
branch as outlined in rule #5.</para> 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> issue since it's the
release engineer who is ultimately responsible (and gets beaten release engineer who is ultimately responsible (and gets beaten
up) if a change turns out to be bad. Please respect this and give 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 the release engineer your full cooperation when it comes to the
-stable branch. The management of -stable may frequently seem to <literal>-STABLE</literal> branch. The management of <literal>-STABLE</literal> may frequently seem to
be overly conservative to the casual observer, but also bear in be overly conservative to the casual observer, but also bear in
mind the fact that conservatism is supposed to be the hallmark of mind the fact that conservatism is supposed to be the hallmark of
-stable and different rules apply there than in -current. There's <literal>-STABLE</literal> and different rules apply there than in <literal>-CURRENT</literal>. There's
also really no point in having -current be a testing ground if also really no point in having <literal>-CURRENT</literal> be a testing ground if
changes are merged over from -stable immediately without giving changes are merged over to <literal>-STABLE</literal> immediately. Changes need
them a chance be tested by the -current developers, so allow some a chance to be tested by the <literal>-CURRENT</literal> developers, so allow some
time to elapse before merging unless the -stable fix is critical, 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 fixes,
etc.) In other words, apply common sense.</para> etc.) In other words, apply common sense.</para>
@ -693,28 +693,28 @@
<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 bad. If
you must &ldquo;strongly disagree&rdquo; about something, do so you must <quote>strongly disagree</quote> about something, do so
only in private.</para> 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 image is
very important to all of us, especially if we're to continue to very important to all of us, especially if we are to continue to
attract new members. There will be occasions when, despite attract new members. There will be occasions when, despite
everyone's very best attempts at self-control, tempers are lost 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 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. minimize the effects of this until everyone has cooled back down.
That means that you shouldn't air your angry words in public and That means that you should not air your angry words in public and
you shouldn't forward private correspondence to public mailing you should not forward private correspondence to public mailing
lists or aliases. What people say one-to-one is often much less lists or aliases. What people say one-to-one is often much less
sugar-coated than what they'd say in public, and such sugar-coated than what they would say in public, and such
communications therefore have no place there - they only serve to communications therefore have no place there - they only serve to
inflame an already bad situation. If the person sending you a inflame an already bad situation. If the person sending you a
flame-o-gram had at least the grace to send it privately, then flame-o-gram at least had the grace to send it privately, then
have the grace to keep it private yourself. If you feel you're have the grace to keep it private yourself. If you feel you are
being unfairly treated by another developer and it's causing you being unfairly treated by another developer, and it is causing you
anguish, bring the matter up with core rather than taking it anguish, bring the matter up with core rather than taking it
public. We'll do our best to play peace makers and get things public. We will do our best to play peace makers and get things
back to sanity. In cases where the dispute involves a change to back to sanity. In cases where the dispute involves a change to
the codebase and the participants don't appear to be reaching an the codebase and the participants do not appear to be reaching an
amicable agreement, core may appoint a mutually-agreeable 3rd amicable agreement, core may appoint a mutually-agreeable 3rd
party to resolve the dispute. All parties involved must then 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
@ -722,7 +722,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the committers mailing list <para>Respect all code freezes and read the <literal>committers</literal> mailing list
on a timely basis so you know when they are.</para> 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 big
@ -737,14 +737,14 @@
<listitem> <listitem>
<para>When in doubt on any procedure, ask first!</para> <para>When in doubt on any procedure, ask first!</para>
<para>So many mistakes are made because someone's in a hurry and <para>Many mistakes are made because someone is in a hurry and
just assumes they know the right way of going about something. If just assumes they know the right way of doing something. If
you haven't done it before, chances are good that you don't you have not done it before, chances are good that you do not
actually know the way we do things and really need to ask first or 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 you are going to completely embarrass yourself in public. There's
no shame in asking &ldquo;how in the heck do I do this?&rdquo; and no shame in asking <quote>how in the heck do I do this?</quote>
we already know you're an intelligent person or you wouldn't be in We already know you are an intelligent person; otherwise, you would not be a
committers.</para> committer.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -772,7 +772,7 @@
<sect2> <sect2>
<title>Other Suggestions</title> <title>Other Suggestions</title>
<para>When committing documentation changes, also be sure and use a <para>When committing documentation changes, use a
spell checker before committing. :) For all SGML docs, you should spell checker before committing. :) For all SGML docs, you should
also verify that your formatting directives are correct by running also verify that your formatting directives are correct by running
<command>make lint</command>.</para> <command>make lint</command>.</para>
@ -782,10 +782,13 @@
are correct and that the man page has all of the appropriate are correct and that the man page has all of the appropriate
<makevar>MLINK</makevar>s installed.</para> <makevar>MLINK</makevar>s installed.</para>
<para>Do not mix style fixes with new functionality. It makes <para>Do not mix style fixes with new functionality. A style
the diffs hard to read, and hides the new bugs. Do not fix is any change which does not modify the functionality of
the code. Mixing the changes ofucsates the functionality
change when using <command>cvs diff</command>, which can hide
any new bugs. Do not
include whitespace changes with content changes in commits to include whitespace changes with content changes in commits to
<filename>doc/</filename> or <filename>www/</filename>. It <filename>doc/</filename> or <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 any
style or whitespace changes in seperate commits that are clearly style or whitespace changes in seperate commits that are clearly
labeled as such in the commit message.</para> labeled as such in the commit message.</para>
@ -808,11 +811,11 @@
<para>First, please read the section about repository <para>First, please read the section about repository
copy.</para> copy.</para>
<para>To import a new port, the easiest way is to use the <para>The easiest way to import a new port is to use the
<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
specifies. It will also add an entry to the modules specify. It will also add an entry to the <filename>CVSROOT/modules</filename>
file. It was written by &a.joerg; so please send mail file. It was written by &a.joerg; so please send mail
to him if you have questions about to him if you have questions about
<command>easy-import</command>.</para> <command>easy-import</command>.</para>
@ -890,8 +893,8 @@
<para>Another example is when a port is moved from one <para>Another example is when a port is moved from one
subdirectory to another, or when you want to change the subdirectory to another, or when you want to change the
name of a directory due to the authors calling their name of a directory because the author(s) renamed their
software by a different name even though it's a software even though it is a
descendant of a port already in a tree.</para> descendant of a port already in a tree.</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -1119,13 +1122,13 @@
</question> </question>
<answer> <answer>
<para>Any file right under <filename>ports/</filename>, or <para>Any file directly under <filename>ports/</filename>, or
any file under a subdirectory that starts with an any file under a subdirectory that starts with an
uppercase letter (<filename>Mk</filename>, uppercase letter (<filename>Mk/</filename>,
<filename>Tools</filename>, etc.). In particular, the <filename>Tools/</filename>, etc.). In particular, the
ports manager is very protective about ports manager is very protective of
<filename>ports/Mk/bsd.port.mk</filename> so don't <filename>ports/Mk/bsd.port*.mk</filename> so don't
commit changes to it unless you want to face his commit changes to those files unless you want to face his
wra(i)th.</para> wra(i)th.</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -1185,10 +1188,10 @@
is duplicated in the 1.2 delta. Now, repeat this for 2000 files is duplicated in the 1.2 delta. Now, repeat this for 2000 files
in a large directory, it adds up a lot.</para> in a large directory, it adds up a lot.</para>
<para><emphasis>This</emphasis> is why we have such &ldquo;hands <para><emphasis>This</emphasis> is why we have such <quote>hands
off&rdquo; policies for src/contrib and other things that track off</quote> policies for <filename>src/contrib</filename> and other things that track
the vendor releases. This is why &ldquo;typo fixes&rdquo; in man the vendor releases. This is why <quote>typo fixes</quote> in man
pages and spelling &ldquo;corrections&rdquo; are so strongly pages and spelling <quote>corrections</quote> are so strongly
discouraged for vendor code.</para> discouraged for vendor code.</para>
</answer> </answer>
</qandaentry> </qandaentry>

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

@ -180,12 +180,12 @@
your way!</para> your way!</para>
<para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid> <para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid>
and create yourself a and create a
<filename>/var/forward/<replaceable>user</replaceable></filename> <filename>/var/forward/<replaceable>user</replaceable></filename>
(where <replaceable>user</replaceable> is your username) file (where <replaceable>user</replaceable> is your username) file
which contains your principal e-mail address where you want mail 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. Really large mailboxes which have taken up 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
permanent residence on <hostid>hub</hostid> often get permanent residence on <hostid>hub</hostid> often get
<quote>accidently</quote> truncated without warning, so forward <quote>accidently</quote> truncated without warning, so forward
it or read it and you will not lose it.</para> it or read it and you will not lose it.</para>
@ -216,7 +216,7 @@
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-all</literal> mailing list that you can really get <literal>cvs-committers</literal> mailing list that you can really get
a feel for just what is and is not) then consider sending the a feel for just what is and is not) then consider sending the
change to them instead, just as you would have before becoming a change to them instead, just as you would have before becoming a
committer. For ports, you should contact the listed committer. For ports, you should contact the listed
@ -224,7 +224,7 @@
<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. 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,9 +289,9 @@
<term>&a.asami;</term> <term>&a.asami;</term>
<listitem> <listitem>
<para>Is the portsmeister, meaning that he has ultimate <para>Satoshi is the Ports Wraith, meaning that he has ultimate
authority over any modifications to the ports collection or authority over any modifications to the ports collection or
ports make macro files. He is also the one responsible for the ports skeleton makefiles. He is also the one responsible for
administering code freezes before the releases.</para> administering code freezes before the releases.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -300,9 +300,9 @@
<term>&a.bde;</term> <term>&a.bde;</term>
<listitem> <listitem>
<para>Is Obersturmbahnfuhrer of the Style Police. When you <para>Bruce is the Obersturmbahnfuhrer of the Style Police. When you
do a commit that could have been done better, Bruce will do a commit that could have been done better, Bruce will
be there to note it to you. Be thankful that someone be there to tell you. Be thankful that someone
is.</para> is.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -311,13 +311,13 @@
<term>&a.dg;</term> <term>&a.dg;</term>
<listitem> <listitem>
<para>Is our principal architect and overseer of the VM <para>David is our principal architect and overseer of the VM
system. If you have a VM system change in mind, system. If you have a VM system change in mind,
coordinate it with David. Should you become locked in 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 can also occasionally be and make a final decision might be
necessary.</para> necessary.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -326,7 +326,7 @@
<term>&a.jkh;</term> <term>&a.jkh;</term>
<listitem> <listitem>
<para>Is the release engineer. He is responsible for <para>Jordan is the release engineer. He is responsible for
setting release deadlines and controlling the release setting release deadlines and controlling the release
process. During code freezes, he also has final authority process. During code freezes, he also has final authority
on all changes to the system for whichever branch is on all changes to the system for whichever branch is
@ -334,7 +334,7 @@
merged from <literal>-CURRENT</literal> to merged from <literal>-CURRENT</literal> to
<literal>-STABLE</literal> (whatever values those may have <literal>-STABLE</literal> (whatever values those may have
at any given time), he is also the one to talk to about at any given time), he is also the one to talk to about
it</para> it.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -354,10 +354,10 @@
<term>&a.steve;</term> <term>&a.steve;</term>
<listitem> <listitem>
<para>Steve is unofficial maintainer of <para>Steve is the unofficial maintainer of
<filename>/usr/src/bin</filename>. If you have something <filename>src/bin</filename>. If you have something
significant you'd like to do there, you should probably significant you'd like to do there, you should probably
coordinate it first with Steve. He's also Problem coordinate it with Steve first. He is also a Problem
Report-meister, along with &a.phk;.</para> Report-meister, along with &a.phk;.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -458,9 +458,9 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Respect existing maintainers if listed <para>Respect existing maintainers if listed in the
(<makevar>MAINTAINER</makevar> field in (<makevar>MAINTAINER</makevar> field in
<filename>Makefile</filename> or <filename>MAINTAINER</filename> <filename>Makefile</filename> or in the <filename>MAINTAINER</filename>
file in the top-level directory).</para> file in the top-level directory).</para>
</listitem> </listitem>
@ -476,23 +476,23 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Changes go to -current before -stable unless specifically <para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically
permitted by the release engineer or unless they're not applicable permitted by the release engineer or unless they're not applicable
to -current. Any non-trivial or non-urgent change which is to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
applicable should also be allowed to sit in -current for at least 3 applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least 3
days before merging so that it can be given sufficient testing. The days before merging so that it can be given sufficient testing. The
release engineer has the same authority over the -stable branch as release engineer has the same authority over the <literal>-STABLE</literal> branch as
outlined for the Principal Architect in rule #5.</para> 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 bad. If
you must "strongly disagree" about something, do so only in you must <quote>strongly disagree</quote> about something, do so only in
private.</para> private.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the committers mailing list on <para>Respect all code freezes and read the <literal>committers</literal> mailing list on
a timely basis so you know when a code freeze is in effect.</para> a timely basis so you know when a code freeze is in effect.</para>
</listitem> </listitem>
@ -510,7 +510,7 @@
Three or more members of core, or the Principal Architect and another Three or more members of core, or the Principal Architect and another
member of core acting in unison, have the power to temporarily suspend member of core acting in unison, have the power to temporarily suspend
commit privileges until <literal>-core</literal> as a whole has the chance to review the commit privileges until <literal>-core</literal> as a whole has the chance to review the
issue. In cases of <quote>emergency</quote> (a committer doing damage to the issue. In case of an <quote>emergency</quote> (a committer doing damage to the
repository), a temporary suspension may also be done by the repository 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 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 time. Only core as a whole has the authority to suspend commit
@ -522,7 +522,7 @@
seriously out of control, it's important to be able to deal with this 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 immediately rather than be paralyzed by debate. In all cases, a
committer whose privileges are suspended or revoked is entitled to a committer whose privileges are suspended or revoked is entitled to a
&ldquo;hearing&rdquo;, the total duration of the suspension being <quote>hearing</quote>, the total duration of the suspension being
determined at that time. A committer whose privileges are suspended may 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 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 thereafter (unless the total suspension period is less than 30 days). A
@ -536,7 +536,7 @@
committers and is bound by the <emphasis>same rules</emphasis>. Just committers and is bound by the <emphasis>same rules</emphasis>. Just
because someone is in core doesn't mean that they have special 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 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 <quote>special powers</quote> only kick in when it acts as a group, not
on an individual basis. As individuals, we are all committers first and on an individual basis. As individuals, we are all committers first and
core second.</para> core second.</para>
@ -570,7 +570,7 @@
the other person(s) that your side of the argument is correct, 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 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 term at the cost of a long-term flame war. Not only is this very
bad &ldquo;energy economics&rdquo;, but repeated displays of bad <quote>energy economics</quote>, but repeated displays of
public aggression which impair our ability to work well together public aggression which impair our ability to work well together
will be dealt with severely by the project leadership and may will be dealt with severely by the project leadership and may
result in suspension or termination of your commit privileges. result in suspension or termination of your commit privileges.
@ -603,9 +603,9 @@
<listitem> <listitem>
<para>Respect existing maintainers if listed.</para> <para>Respect existing maintainers if listed.</para>
<para>Many parts of FreeBSD aren't &ldquo;owned&rdquo; in the sense <para>Many parts of FreeBSD aren't <quote>owned</quote> in the sense
that any specific individual will jump up and yell if you commit a 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 change to <quote>their</quote> area, but it still pays to check
first. One convention we use is to put a maintainer line in the first. One convention we use is to put a maintainer line in the
<filename>Makefile</filename> for any package or subtree which is <filename>Makefile</filename> for any package or subtree which is
being actively maintained by one or more people; see <ulink being actively maintained by one or more people; see <ulink
@ -666,26 +666,26 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Changes go to -current before -stable unless specifically <para>Changes go to <literal>-CURRENT</literal> before <literal>-STABLE</literal> unless specifically
permitted by the release engineer or unless they're not applicable permitted by the release engineer or unless they're not applicable
to -current. Any non-trivial or non-urgent change which is to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
applicable should also be allowed to sit in -current for at least applicable should also be allowed to sit in <literal>-CURRENT</literal> for at least
3 days before merging so that it can be given sufficient testing. 3 days before merging so that it can be given sufficient testing.
The release engineer has the same authority over the -stable The release engineer has the same authority over the <literal>-STABLE</literal>
branch as outlined in rule #5.</para> 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> issue since it's the
release engineer who is ultimately responsible (and gets beaten release engineer who is ultimately responsible (and gets beaten
up) if a change turns out to be bad. Please respect this and give 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 the release engineer your full cooperation when it comes to the
-stable branch. The management of -stable may frequently seem to <literal>-STABLE</literal> branch. The management of <literal>-STABLE</literal> may frequently seem to
be overly conservative to the casual observer, but also bear in be overly conservative to the casual observer, but also bear in
mind the fact that conservatism is supposed to be the hallmark of mind the fact that conservatism is supposed to be the hallmark of
-stable and different rules apply there than in -current. There's <literal>-STABLE</literal> and different rules apply there than in <literal>-CURRENT</literal>. There's
also really no point in having -current be a testing ground if also really no point in having <literal>-CURRENT</literal> be a testing ground if
changes are merged over from -stable immediately without giving changes are merged over to <literal>-STABLE</literal> immediately. Changes need
them a chance be tested by the -current developers, so allow some a chance to be tested by the <literal>-CURRENT</literal> developers, so allow some
time to elapse before merging unless the -stable fix is critical, 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 fixes,
etc.) In other words, apply common sense.</para> etc.) In other words, apply common sense.</para>
@ -693,28 +693,28 @@
<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 bad. If
you must &ldquo;strongly disagree&rdquo; about something, do so you must <quote>strongly disagree</quote> about something, do so
only in private.</para> 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 image is
very important to all of us, especially if we're to continue to very important to all of us, especially if we are to continue to
attract new members. There will be occasions when, despite attract new members. There will be occasions when, despite
everyone's very best attempts at self-control, tempers are lost 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 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. minimize the effects of this until everyone has cooled back down.
That means that you shouldn't air your angry words in public and That means that you should not air your angry words in public and
you shouldn't forward private correspondence to public mailing you should not forward private correspondence to public mailing
lists or aliases. What people say one-to-one is often much less lists or aliases. What people say one-to-one is often much less
sugar-coated than what they'd say in public, and such sugar-coated than what they would say in public, and such
communications therefore have no place there - they only serve to communications therefore have no place there - they only serve to
inflame an already bad situation. If the person sending you a inflame an already bad situation. If the person sending you a
flame-o-gram had at least the grace to send it privately, then flame-o-gram at least had the grace to send it privately, then
have the grace to keep it private yourself. If you feel you're have the grace to keep it private yourself. If you feel you are
being unfairly treated by another developer and it's causing you being unfairly treated by another developer, and it is causing you
anguish, bring the matter up with core rather than taking it anguish, bring the matter up with core rather than taking it
public. We'll do our best to play peace makers and get things public. We will do our best to play peace makers and get things
back to sanity. In cases where the dispute involves a change to back to sanity. In cases where the dispute involves a change to
the codebase and the participants don't appear to be reaching an the codebase and the participants do not appear to be reaching an
amicable agreement, core may appoint a mutually-agreeable 3rd amicable agreement, core may appoint a mutually-agreeable 3rd
party to resolve the dispute. All parties involved must then 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
@ -722,7 +722,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Respect all code freezes and read the committers mailing list <para>Respect all code freezes and read the <literal>committers</literal> mailing list
on a timely basis so you know when they are.</para> 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 big
@ -737,14 +737,14 @@
<listitem> <listitem>
<para>When in doubt on any procedure, ask first!</para> <para>When in doubt on any procedure, ask first!</para>
<para>So many mistakes are made because someone's in a hurry and <para>Many mistakes are made because someone is in a hurry and
just assumes they know the right way of going about something. If just assumes they know the right way of doing something. If
you haven't done it before, chances are good that you don't you have not done it before, chances are good that you do not
actually know the way we do things and really need to ask first or 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 you are going to completely embarrass yourself in public. There's
no shame in asking &ldquo;how in the heck do I do this?&rdquo; and no shame in asking <quote>how in the heck do I do this?</quote>
we already know you're an intelligent person or you wouldn't be in We already know you are an intelligent person; otherwise, you would not be a
committers.</para> committer.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -772,7 +772,7 @@
<sect2> <sect2>
<title>Other Suggestions</title> <title>Other Suggestions</title>
<para>When committing documentation changes, also be sure and use a <para>When committing documentation changes, use a
spell checker before committing. :) For all SGML docs, you should spell checker before committing. :) For all SGML docs, you should
also verify that your formatting directives are correct by running also verify that your formatting directives are correct by running
<command>make lint</command>.</para> <command>make lint</command>.</para>
@ -782,10 +782,13 @@
are correct and that the man page has all of the appropriate are correct and that the man page has all of the appropriate
<makevar>MLINK</makevar>s installed.</para> <makevar>MLINK</makevar>s installed.</para>
<para>Do not mix style fixes with new functionality. It makes <para>Do not mix style fixes with new functionality. A style
the diffs hard to read, and hides the new bugs. Do not fix is any change which does not modify the functionality of
the code. Mixing the changes ofucsates the functionality
change when using <command>cvs diff</command>, which can hide
any new bugs. Do not
include whitespace changes with content changes in commits to include whitespace changes with content changes in commits to
<filename>doc/</filename> or <filename>www/</filename>. It <filename>doc/</filename> or <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 any
style or whitespace changes in seperate commits that are clearly style or whitespace changes in seperate commits that are clearly
labeled as such in the commit message.</para> labeled as such in the commit message.</para>
@ -808,11 +811,11 @@
<para>First, please read the section about repository <para>First, please read the section about repository
copy.</para> copy.</para>
<para>To import a new port, the easiest way is to use the <para>The easiest way to import a new port is to use the
<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
specifies. It will also add an entry to the modules specify. It will also add an entry to the <filename>CVSROOT/modules</filename>
file. It was written by &a.joerg; so please send mail file. It was written by &a.joerg; so please send mail
to him if you have questions about to him if you have questions about
<command>easy-import</command>.</para> <command>easy-import</command>.</para>
@ -890,8 +893,8 @@
<para>Another example is when a port is moved from one <para>Another example is when a port is moved from one
subdirectory to another, or when you want to change the subdirectory to another, or when you want to change the
name of a directory due to the authors calling their name of a directory because the author(s) renamed their
software by a different name even though it's a software even though it is a
descendant of a port already in a tree.</para> descendant of a port already in a tree.</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -1119,13 +1122,13 @@
</question> </question>
<answer> <answer>
<para>Any file right under <filename>ports/</filename>, or <para>Any file directly under <filename>ports/</filename>, or
any file under a subdirectory that starts with an any file under a subdirectory that starts with an
uppercase letter (<filename>Mk</filename>, uppercase letter (<filename>Mk/</filename>,
<filename>Tools</filename>, etc.). In particular, the <filename>Tools/</filename>, etc.). In particular, the
ports manager is very protective about ports manager is very protective of
<filename>ports/Mk/bsd.port.mk</filename> so don't <filename>ports/Mk/bsd.port*.mk</filename> so don't
commit changes to it unless you want to face his commit changes to those files unless you want to face his
wra(i)th.</para> wra(i)th.</para>
</answer> </answer>
</qandaentry> </qandaentry>
@ -1185,10 +1188,10 @@
is duplicated in the 1.2 delta. Now, repeat this for 2000 files is duplicated in the 1.2 delta. Now, repeat this for 2000 files
in a large directory, it adds up a lot.</para> in a large directory, it adds up a lot.</para>
<para><emphasis>This</emphasis> is why we have such &ldquo;hands <para><emphasis>This</emphasis> is why we have such <quote>hands
off&rdquo; policies for src/contrib and other things that track off</quote> policies for <filename>src/contrib</filename> and other things that track
the vendor releases. This is why &ldquo;typo fixes&rdquo; in man the vendor releases. This is why <quote>typo fixes</quote> in man
pages and spelling &ldquo;corrections&rdquo; are so strongly pages and spelling <quote>corrections</quote> are so strongly
discouraged for vendor code.</para> discouraged for vendor code.</para>
</answer> </answer>
</qandaentry> </qandaentry>