Patch to the committers guide including several grammar fixes, markup
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:
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
|
@ -180,12 +180,12 @@
|
|||
your way!</para>
|
||||
|
||||
<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>
|
||||
(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 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
|
||||
<quote>accidently</quote> truncated without warning, so forward
|
||||
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
|
||||
about to modify something which is clearly being actively
|
||||
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
|
||||
change to them instead, just as you would have before becoming a
|
||||
committer. For ports, you should contact the listed
|
||||
|
@ -224,7 +224,7 @@
|
|||
<filename>Makefile</filename>. For other parts of the
|
||||
repository, if you are unsure who the active maintainer might
|
||||
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
|
||||
proprietary interest in the area affected, go ahead and commit
|
||||
it.</para>
|
||||
|
@ -289,9 +289,9 @@
|
|||
<term>&a.asami;</term>
|
||||
|
||||
<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
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -300,9 +300,9 @@
|
|||
<term>&a.bde;</term>
|
||||
|
||||
<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
|
||||
be there to note it to you. Be thankful that someone
|
||||
be there to tell you. Be thankful that someone
|
||||
is.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -311,13 +311,13 @@
|
|||
<term>&a.dg;</term>
|
||||
|
||||
<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,
|
||||
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
|
||||
a proposed change (which does not happen very often,
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -326,7 +326,7 @@
|
|||
<term>&a.jkh;</term>
|
||||
|
||||
<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
|
||||
process. During code freezes, he also has final authority
|
||||
on all changes to the system for whichever branch is
|
||||
|
@ -334,7 +334,7 @@
|
|||
merged from <literal>-CURRENT</literal> to
|
||||
<literal>-STABLE</literal> (whatever values those may have
|
||||
at any given time), he is also the one to talk to about
|
||||
it</para>
|
||||
it.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
@ -354,10 +354,10 @@
|
|||
<term>&a.steve;</term>
|
||||
|
||||
<listitem>
|
||||
<para>Steve is unofficial maintainer of
|
||||
<filename>/usr/src/bin</filename>. If you have something
|
||||
<para>Steve is the unofficial maintainer of
|
||||
<filename>src/bin</filename>. If you have something
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -458,9 +458,9 @@
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Respect existing maintainers if listed
|
||||
<para>Respect existing maintainers if listed in the
|
||||
(<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>
|
||||
</listitem>
|
||||
|
||||
|
@ -476,23 +476,23 @@
|
|||
</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
|
||||
to -current. Any non-trivial or non-urgent change which is
|
||||
applicable should also be allowed to sit in -current for at least 3
|
||||
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
|
||||
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
|
||||
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>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Don't fight in public with other committers; it looks bad. If
|
||||
you must "strongly disagree" about something, do so only in
|
||||
you must <quote>strongly disagree</quote> about something, do so only in
|
||||
private.</para>
|
||||
</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>
|
||||
</listitem>
|
||||
|
||||
|
@ -510,7 +510,7 @@
|
|||
Three or more members of core, or the Principal Architect and another
|
||||
member of core acting in unison, have the power to temporarily suspend
|
||||
commit privileges until <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
|
||||
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
|
||||
|
@ -522,7 +522,7 @@
|
|||
seriously out of control, it's important to be able to deal with this
|
||||
immediately rather than be paralyzed by debate. In all cases, a
|
||||
committer whose privileges are suspended or revoked is entitled to a
|
||||
“hearing”, 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
|
||||
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
|
||||
|
@ -536,7 +536,7 @@
|
|||
committers and is bound by the <emphasis>same rules</emphasis>. Just
|
||||
because someone is in core doesn't mean that they have special
|
||||
dispensation to step outside of any of the lines painted here; core's
|
||||
“special powers” 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
|
||||
core second.</para>
|
||||
|
||||
|
@ -570,7 +570,7 @@
|
|||
the other person(s) that your side of the argument is correct,
|
||||
don't just blow off some steam so you can feel better in the short
|
||||
term at the cost of a long-term flame war. Not only is this very
|
||||
bad “energy economics”, but repeated displays of
|
||||
bad <quote>energy economics</quote>, but repeated displays of
|
||||
public aggression which impair our ability to work well together
|
||||
will be dealt with severely by the project leadership and may
|
||||
result in suspension or termination of your commit privileges.
|
||||
|
@ -603,9 +603,9 @@
|
|||
<listitem>
|
||||
<para>Respect existing maintainers if listed.</para>
|
||||
|
||||
<para>Many parts of FreeBSD aren't “owned” 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
|
||||
change to “their” 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
|
||||
<filename>Makefile</filename> for any package or subtree which is
|
||||
being actively maintained by one or more people; see <ulink
|
||||
|
@ -666,26 +666,26 @@
|
|||
</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
|
||||
to -current. Any non-trivial or non-urgent change which is
|
||||
applicable should also be allowed to sit in -current for at least
|
||||
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
|
||||
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 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>
|
||||
|
||||
<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
|
||||
up) if a change turns out to be bad. Please respect this and give
|
||||
the release engineer your full cooperation when it comes to the
|
||||
-stable branch. The management of -stable may frequently seem to
|
||||
<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
|
||||
mind the fact that conservatism is supposed to be the hallmark of
|
||||
-stable and different rules apply there than in -current. There's
|
||||
also really no point in having -current be a testing ground if
|
||||
changes are merged over from -stable immediately without giving
|
||||
them a chance be tested by the -current developers, so allow some
|
||||
time to elapse before merging unless the -stable fix is critical,
|
||||
<literal>-STABLE</literal> and different rules apply there than in <literal>-CURRENT</literal>. There's
|
||||
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
|
||||
unnecessary (spelling fixes to manpages, obvious bug/typo fixes,
|
||||
etc.) In other words, apply common sense.</para>
|
||||
|
@ -693,28 +693,28 @@
|
|||
|
||||
<listitem>
|
||||
<para>Don't fight in public with other committers; it looks bad. If
|
||||
you must “strongly disagree” about something, do so
|
||||
you must <quote>strongly disagree</quote> about something, do so
|
||||
only in private.</para>
|
||||
|
||||
<para>This project has a public image to uphold and that image is
|
||||
very important to all of us, especially if we're to continue to
|
||||
very important to all of us, especially if we are to continue to
|
||||
attract new members. There will be occasions when, despite
|
||||
everyone's very best attempts at self-control, tempers are lost
|
||||
and angry words are exchanged, and the best we can do is try and
|
||||
minimize the effects of this until everyone has cooled back down.
|
||||
That means that you shouldn't air your angry words in public and
|
||||
you shouldn't forward private correspondence to public mailing
|
||||
That means that you should not air your angry words in public and
|
||||
you should not forward private correspondence to public mailing
|
||||
lists or aliases. What people say one-to-one is often much less
|
||||
sugar-coated than what they'd say in public, and such
|
||||
sugar-coated than what they would say in public, and such
|
||||
communications therefore have no place there - they only serve to
|
||||
inflame an already bad situation. If the person sending you a
|
||||
flame-o-gram had at least the grace to send it privately, then
|
||||
have the grace to keep it private yourself. If you feel you're
|
||||
being unfairly treated by another developer and it's causing you
|
||||
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 are
|
||||
being unfairly treated by another developer, and it is causing you
|
||||
anguish, bring the matter up with core rather than taking it
|
||||
public. We'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
|
||||
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
|
||||
party to resolve the dispute. All parties involved must then
|
||||
agree to be bound by the decision reached by this 3rd
|
||||
|
@ -722,7 +722,7 @@
|
|||
</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>
|
||||
|
||||
<para>Committing changes during a code freeze is a really big
|
||||
|
@ -737,14 +737,14 @@
|
|||
<listitem>
|
||||
<para>When in doubt on any procedure, ask first!</para>
|
||||
|
||||
<para>So many mistakes are made because someone's in a hurry and
|
||||
just assumes they know the right way of going about something. If
|
||||
you haven't done it before, chances are good that you don't
|
||||
<para>Many mistakes are made because someone is in a hurry and
|
||||
just assumes they know the right way of doing something. If
|
||||
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
|
||||
you're going to completely embarrass yourself in public. There's
|
||||
no shame in asking “how in the heck do I do this?” and
|
||||
we already know you're an intelligent person or you wouldn't be in
|
||||
committers.</para>
|
||||
you are going to completely embarrass yourself in public. There's
|
||||
no shame in asking <quote>how in the heck do I do this?</quote>
|
||||
We already know you are an intelligent person; otherwise, you would not be a
|
||||
committer.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
@ -772,7 +772,7 @@
|
|||
<sect2>
|
||||
<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
|
||||
also verify that your formatting directives are correct by running
|
||||
<command>make lint</command>.</para>
|
||||
|
@ -782,10 +782,13 @@
|
|||
are correct and that the man page has all of the appropriate
|
||||
<makevar>MLINK</makevar>s installed.</para>
|
||||
|
||||
<para>Do not mix style fixes with new functionality. It makes
|
||||
the diffs hard to read, and hides the new bugs. Do not
|
||||
<para>Do not mix style fixes with new functionality. A style
|
||||
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
|
||||
<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
|
||||
style or whitespace changes in seperate commits that are clearly
|
||||
labeled as such in the commit message.</para>
|
||||
|
@ -808,11 +811,11 @@
|
|||
<para>First, please read the section about repository
|
||||
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
|
||||
<hostid>freefall</hostid>. It will ask you some
|
||||
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
|
||||
to him if you have questions about
|
||||
<command>easy-import</command>.</para>
|
||||
|
@ -890,8 +893,8 @@
|
|||
|
||||
<para>Another example is when a port is moved from one
|
||||
subdirectory to another, or when you want to change the
|
||||
name of a directory due to the authors calling their
|
||||
software by a different name even though it's a
|
||||
name of a directory because the author(s) renamed their
|
||||
software even though it is a
|
||||
descendant of a port already in a tree.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
@ -1119,13 +1122,13 @@
|
|||
</question>
|
||||
|
||||
<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
|
||||
uppercase letter (<filename>Mk</filename>,
|
||||
<filename>Tools</filename>, etc.). In particular, the
|
||||
ports manager is very protective about
|
||||
<filename>ports/Mk/bsd.port.mk</filename> so don't
|
||||
commit changes to it unless you want to face his
|
||||
uppercase letter (<filename>Mk/</filename>,
|
||||
<filename>Tools/</filename>, etc.). In particular, the
|
||||
ports manager is very protective of
|
||||
<filename>ports/Mk/bsd.port*.mk</filename> so don't
|
||||
commit changes to those files unless you want to face his
|
||||
wra(i)th.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
@ -1185,10 +1188,10 @@
|
|||
is duplicated in the 1.2 delta. 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 “hands
|
||||
off” policies for src/contrib and other things that track
|
||||
the vendor releases. This is why “typo fixes” in man
|
||||
pages and spelling “corrections” are so strongly
|
||||
<para><emphasis>This</emphasis> is why we have such <quote>hands
|
||||
off</quote> policies for <filename>src/contrib</filename> and other things that track
|
||||
the vendor releases. This is why <quote>typo fixes</quote> in man
|
||||
pages and spelling <quote>corrections</quote> are so strongly
|
||||
discouraged for vendor code.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
|
|
@ -180,12 +180,12 @@
|
|||
your way!</para>
|
||||
|
||||
<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>
|
||||
(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 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
|
||||
<quote>accidently</quote> truncated without warning, so forward
|
||||
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
|
||||
about to modify something which is clearly being actively
|
||||
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
|
||||
change to them instead, just as you would have before becoming a
|
||||
committer. For ports, you should contact the listed
|
||||
|
@ -224,7 +224,7 @@
|
|||
<filename>Makefile</filename>. For other parts of the
|
||||
repository, if you are unsure who the active maintainer might
|
||||
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
|
||||
proprietary interest in the area affected, go ahead and commit
|
||||
it.</para>
|
||||
|
@ -289,9 +289,9 @@
|
|||
<term>&a.asami;</term>
|
||||
|
||||
<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
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -300,9 +300,9 @@
|
|||
<term>&a.bde;</term>
|
||||
|
||||
<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
|
||||
be there to note it to you. Be thankful that someone
|
||||
be there to tell you. Be thankful that someone
|
||||
is.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -311,13 +311,13 @@
|
|||
<term>&a.dg;</term>
|
||||
|
||||
<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,
|
||||
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
|
||||
a proposed change (which does not happen very often,
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -326,7 +326,7 @@
|
|||
<term>&a.jkh;</term>
|
||||
|
||||
<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
|
||||
process. During code freezes, he also has final authority
|
||||
on all changes to the system for whichever branch is
|
||||
|
@ -334,7 +334,7 @@
|
|||
merged from <literal>-CURRENT</literal> to
|
||||
<literal>-STABLE</literal> (whatever values those may have
|
||||
at any given time), he is also the one to talk to about
|
||||
it</para>
|
||||
it.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
@ -354,10 +354,10 @@
|
|||
<term>&a.steve;</term>
|
||||
|
||||
<listitem>
|
||||
<para>Steve is unofficial maintainer of
|
||||
<filename>/usr/src/bin</filename>. If you have something
|
||||
<para>Steve is the unofficial maintainer of
|
||||
<filename>src/bin</filename>. If you have something
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -458,9 +458,9 @@
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Respect existing maintainers if listed
|
||||
<para>Respect existing maintainers if listed in the
|
||||
(<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>
|
||||
</listitem>
|
||||
|
||||
|
@ -476,23 +476,23 @@
|
|||
</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
|
||||
to -current. Any non-trivial or non-urgent change which is
|
||||
applicable should also be allowed to sit in -current for at least 3
|
||||
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
|
||||
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
|
||||
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>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Don't fight in public with other committers; it looks bad. If
|
||||
you must "strongly disagree" about something, do so only in
|
||||
you must <quote>strongly disagree</quote> about something, do so only in
|
||||
private.</para>
|
||||
</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>
|
||||
</listitem>
|
||||
|
||||
|
@ -510,7 +510,7 @@
|
|||
Three or more members of core, or the Principal Architect and another
|
||||
member of core acting in unison, have the power to temporarily suspend
|
||||
commit privileges until <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
|
||||
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
|
||||
|
@ -522,7 +522,7 @@
|
|||
seriously out of control, it's important to be able to deal with this
|
||||
immediately rather than be paralyzed by debate. In all cases, a
|
||||
committer whose privileges are suspended or revoked is entitled to a
|
||||
“hearing”, 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
|
||||
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
|
||||
|
@ -536,7 +536,7 @@
|
|||
committers and is bound by the <emphasis>same rules</emphasis>. Just
|
||||
because someone is in core doesn't mean that they have special
|
||||
dispensation to step outside of any of the lines painted here; core's
|
||||
“special powers” 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
|
||||
core second.</para>
|
||||
|
||||
|
@ -570,7 +570,7 @@
|
|||
the other person(s) that your side of the argument is correct,
|
||||
don't just blow off some steam so you can feel better in the short
|
||||
term at the cost of a long-term flame war. Not only is this very
|
||||
bad “energy economics”, but repeated displays of
|
||||
bad <quote>energy economics</quote>, but repeated displays of
|
||||
public aggression which impair our ability to work well together
|
||||
will be dealt with severely by the project leadership and may
|
||||
result in suspension or termination of your commit privileges.
|
||||
|
@ -603,9 +603,9 @@
|
|||
<listitem>
|
||||
<para>Respect existing maintainers if listed.</para>
|
||||
|
||||
<para>Many parts of FreeBSD aren't “owned” 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
|
||||
change to “their” 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
|
||||
<filename>Makefile</filename> for any package or subtree which is
|
||||
being actively maintained by one or more people; see <ulink
|
||||
|
@ -666,26 +666,26 @@
|
|||
</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
|
||||
to -current. Any non-trivial or non-urgent change which is
|
||||
applicable should also be allowed to sit in -current for at least
|
||||
to <literal>-CURRENT</literal>. Any non-trivial or non-urgent change which is
|
||||
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 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>
|
||||
|
||||
<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
|
||||
up) if a change turns out to be bad. Please respect this and give
|
||||
the release engineer your full cooperation when it comes to the
|
||||
-stable branch. The management of -stable may frequently seem to
|
||||
<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
|
||||
mind the fact that conservatism is supposed to be the hallmark of
|
||||
-stable and different rules apply there than in -current. There's
|
||||
also really no point in having -current be a testing ground if
|
||||
changes are merged over from -stable immediately without giving
|
||||
them a chance be tested by the -current developers, so allow some
|
||||
time to elapse before merging unless the -stable fix is critical,
|
||||
<literal>-STABLE</literal> and different rules apply there than in <literal>-CURRENT</literal>. There's
|
||||
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
|
||||
unnecessary (spelling fixes to manpages, obvious bug/typo fixes,
|
||||
etc.) In other words, apply common sense.</para>
|
||||
|
@ -693,28 +693,28 @@
|
|||
|
||||
<listitem>
|
||||
<para>Don't fight in public with other committers; it looks bad. If
|
||||
you must “strongly disagree” about something, do so
|
||||
you must <quote>strongly disagree</quote> about something, do so
|
||||
only in private.</para>
|
||||
|
||||
<para>This project has a public image to uphold and that image is
|
||||
very important to all of us, especially if we're to continue to
|
||||
very important to all of us, especially if we are to continue to
|
||||
attract new members. There will be occasions when, despite
|
||||
everyone's very best attempts at self-control, tempers are lost
|
||||
and angry words are exchanged, and the best we can do is try and
|
||||
minimize the effects of this until everyone has cooled back down.
|
||||
That means that you shouldn't air your angry words in public and
|
||||
you shouldn't forward private correspondence to public mailing
|
||||
That means that you should not air your angry words in public and
|
||||
you should not forward private correspondence to public mailing
|
||||
lists or aliases. What people say one-to-one is often much less
|
||||
sugar-coated than what they'd say in public, and such
|
||||
sugar-coated than what they would say in public, and such
|
||||
communications therefore have no place there - they only serve to
|
||||
inflame an already bad situation. If the person sending you a
|
||||
flame-o-gram had at least the grace to send it privately, then
|
||||
have the grace to keep it private yourself. If you feel you're
|
||||
being unfairly treated by another developer and it's causing you
|
||||
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 are
|
||||
being unfairly treated by another developer, and it is causing you
|
||||
anguish, bring the matter up with core rather than taking it
|
||||
public. We'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
|
||||
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
|
||||
party to resolve the dispute. All parties involved must then
|
||||
agree to be bound by the decision reached by this 3rd
|
||||
|
@ -722,7 +722,7 @@
|
|||
</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>
|
||||
|
||||
<para>Committing changes during a code freeze is a really big
|
||||
|
@ -737,14 +737,14 @@
|
|||
<listitem>
|
||||
<para>When in doubt on any procedure, ask first!</para>
|
||||
|
||||
<para>So many mistakes are made because someone's in a hurry and
|
||||
just assumes they know the right way of going about something. If
|
||||
you haven't done it before, chances are good that you don't
|
||||
<para>Many mistakes are made because someone is in a hurry and
|
||||
just assumes they know the right way of doing something. If
|
||||
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
|
||||
you're going to completely embarrass yourself in public. There's
|
||||
no shame in asking “how in the heck do I do this?” and
|
||||
we already know you're an intelligent person or you wouldn't be in
|
||||
committers.</para>
|
||||
you are going to completely embarrass yourself in public. There's
|
||||
no shame in asking <quote>how in the heck do I do this?</quote>
|
||||
We already know you are an intelligent person; otherwise, you would not be a
|
||||
committer.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
@ -772,7 +772,7 @@
|
|||
<sect2>
|
||||
<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
|
||||
also verify that your formatting directives are correct by running
|
||||
<command>make lint</command>.</para>
|
||||
|
@ -782,10 +782,13 @@
|
|||
are correct and that the man page has all of the appropriate
|
||||
<makevar>MLINK</makevar>s installed.</para>
|
||||
|
||||
<para>Do not mix style fixes with new functionality. It makes
|
||||
the diffs hard to read, and hides the new bugs. Do not
|
||||
<para>Do not mix style fixes with new functionality. A style
|
||||
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
|
||||
<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
|
||||
style or whitespace changes in seperate commits that are clearly
|
||||
labeled as such in the commit message.</para>
|
||||
|
@ -808,11 +811,11 @@
|
|||
<para>First, please read the section about repository
|
||||
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
|
||||
<hostid>freefall</hostid>. It will ask you some
|
||||
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
|
||||
to him if you have questions about
|
||||
<command>easy-import</command>.</para>
|
||||
|
@ -890,8 +893,8 @@
|
|||
|
||||
<para>Another example is when a port is moved from one
|
||||
subdirectory to another, or when you want to change the
|
||||
name of a directory due to the authors calling their
|
||||
software by a different name even though it's a
|
||||
name of a directory because the author(s) renamed their
|
||||
software even though it is a
|
||||
descendant of a port already in a tree.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
@ -1119,13 +1122,13 @@
|
|||
</question>
|
||||
|
||||
<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
|
||||
uppercase letter (<filename>Mk</filename>,
|
||||
<filename>Tools</filename>, etc.). In particular, the
|
||||
ports manager is very protective about
|
||||
<filename>ports/Mk/bsd.port.mk</filename> so don't
|
||||
commit changes to it unless you want to face his
|
||||
uppercase letter (<filename>Mk/</filename>,
|
||||
<filename>Tools/</filename>, etc.). In particular, the
|
||||
ports manager is very protective of
|
||||
<filename>ports/Mk/bsd.port*.mk</filename> so don't
|
||||
commit changes to those files unless you want to face his
|
||||
wra(i)th.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
@ -1185,10 +1188,10 @@
|
|||
is duplicated in the 1.2 delta. 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 “hands
|
||||
off” policies for src/contrib and other things that track
|
||||
the vendor releases. This is why “typo fixes” in man
|
||||
pages and spelling “corrections” are so strongly
|
||||
<para><emphasis>This</emphasis> is why we have such <quote>hands
|
||||
off</quote> policies for <filename>src/contrib</filename> and other things that track
|
||||
the vendor releases. This is why <quote>typo fixes</quote> in man
|
||||
pages and spelling <quote>corrections</quote> are so strongly
|
||||
discouraged for vendor code.</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
|
|
Loading…
Reference in a new issue