1116 lines
44 KiB
Text
1116 lines
44 KiB
Text
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
|
|
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
|
|
%man;
|
|
|
|
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
|
|
%authors;
|
|
]>
|
|
|
|
<article>
|
|
<artheader>
|
|
<title>New Committer Guide</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<surname>The FreeBSD Documentation Project</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate>September 1999</pubdate>
|
|
|
|
<copyright>
|
|
<year>1999</year>
|
|
<holder>The FreeBSD Documentation Project</holder>
|
|
</copyright>
|
|
|
|
<abstract>
|
|
<para>Welcome, new committer, to the FreeBSD development
|
|
team!</para>
|
|
|
|
<para>The following docs are provided to orient you on doing CVS
|
|
operations on the FreeBSD central repository machine. A basic
|
|
familiarity with CVS is already assumed, although CVS
|
|
reference information, tutorials, and FAQs can also be found
|
|
at: <ulink url="http://www.cyclic.com/cyclic-pages/books.html">http://www.cyclic.com/cyclic-pages/books.html</ulink></para>
|
|
|
|
<para>Good luck, and welcome aboard!</para>
|
|
</abstract>
|
|
</artheader>
|
|
|
|
<sect1 id="admin">
|
|
<title>Administrative Details</title>
|
|
|
|
<informaltable frame="none" orient="port">
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis>Main Repository Host</emphasis></entry>
|
|
<entry><hostid>freefall.FreeBSD.org</hostid></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<emphasis>International Crypto Repository Host</emphasis>
|
|
</entry>
|
|
<entry><hostid>internat.FreeBSD.org</hostid></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Login Methods</emphasis></entry>
|
|
<entry>&man.ssh.1;</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Main CVSROOT</emphasis></entry>
|
|
<entry>/home/ncvs</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>International Crypto CVSROOT</emphasis></entry>
|
|
<entry>/home/cvs.crypt</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Main CVS Repository Meisters</emphasis></entry>
|
|
<entry>&a.jdp; and &a.peter; as well as &a.asami; for
|
|
<filename>ports/</filename></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<emphasis>International Crypto CVS Repository Meister</emphasis>
|
|
</entry>
|
|
<entry>&a.markm;</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Mailing List</emphasis></entry>
|
|
<entry><email>cvs-committers@FreeBSD.org</email></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
|
|
<entry>RELENG_3 (3.x-STABLE), HEAD (-CURRENT)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>It is required that you use &man.ssh.1; or &man.telnet.1;
|
|
with Kerberos 5 to connect to the repository hosts. These are
|
|
generally more secure than plain &man.telnet.1; or
|
|
&man.rlogin.1; since credential negotiation will always be
|
|
encrypted. All traffic is encrypted by default with &man.ssh.1;.
|
|
With utilities like &man.ssh-agent.1; and &man.scp.1; also
|
|
available, &man.ssh.1; is also far more convenient. If you do
|
|
not know anything about &man.ssh.1, please see
|
|
<xref linkend="ssh.guide">.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="cvs.operations">
|
|
<title>CVS Operations</title>
|
|
|
|
<para>CVS operations are usually done by logging into
|
|
<hostid>freefall</hostid>, making sure the
|
|
<envar>CVSROOT</envar> environment variable is set to
|
|
<filename>/home/ncvs</filename>, and then doing the appropriate
|
|
check-out/check-in operations. If you wish to add
|
|
something which is wholly new (like new ports, contrib-ified
|
|
sources, etc), a script called <quote>easy-import</quote> is
|
|
also provided for making the process easier. It automatically
|
|
adds the new module entry, does the appropriate thing with
|
|
<command>cvs import</command>, etc. – just run it without
|
|
arguments and it will prompt you for everything it needs to
|
|
know.</para>
|
|
|
|
<para>If you are familiar with remote CVS and consider yourself
|
|
pretty studly with CVS in general, you can also do CVS
|
|
operations directly from your own machine and local working
|
|
sources. Just remember to set <envar>CVS_RSH</envar> to
|
|
<wordasword>ssh</wordasword> so that you are using a relatively
|
|
secure and reliable transport. If you have no idea what any of
|
|
the above even means, on the other hand, then please stick with
|
|
logging into <hostid>freefall</hostid> and applying your diffs
|
|
with &man.patch.1;.</para>
|
|
|
|
<para>If you need to use CVS <command>add</command> and
|
|
<command>delete</command> operations in a manner that is
|
|
effectively a <quote>mv</quote> operation, then a repository
|
|
copy is in order rather than your CVS <command>add</command> and
|
|
<command>delete</command>. In a repository copy, a <link
|
|
linkend="conventions">CVS Meister</link> will copy the file(s)
|
|
to their new name and/or location and let you know when it is
|
|
done. The purpose of a repository copy is to preserve file
|
|
change history, or logs. We in the FreeBSD Project greatly
|
|
value the change history CVS gives to the project.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="conventions">
|
|
<title>Conventions and Traditions</title>
|
|
|
|
<para>The CVS Repository Meisters (Peter Wemm and John Polstra)
|
|
are the <quote>owners</quote> of the CVS repository and
|
|
responsible for any and <emphasis>all</emphasis> direct
|
|
modification of it for the purposes of cleanup or fixing some
|
|
grievous abuse of CVS by a committer. No one else should
|
|
attempt to touch the repository directly. Should you cause some
|
|
repository accident, say a bad cvs import or tag operation, do
|
|
<emphasis role="bold">not</emphasis> attempt to fix it yourself!
|
|
Mail or call John or Peter immediately and report the problem to
|
|
one of them instead. The only ones allowed to directly fiddle
|
|
the repository bits are the repomeisters. Satoshi Asami is also a
|
|
repomeister for the <filename>ports/</filename> portion of the
|
|
tree. Mark Murray is the repomeister for the International
|
|
Crypto Repository in South Africa.</para>
|
|
|
|
<para>If you are a new committer, your very first commit should be
|
|
to add yourself to the developer's section (28.2) of the
|
|
Handbook. Figuring out how to check the handbook out and add an
|
|
entry for yourself is relatively easy but still remains a good
|
|
first test of your CVS skills. If you can handle that one,
|
|
you are probably going to be ok.</para>
|
|
|
|
<para>Your next step should be to introduce yourself to the other
|
|
committers, otherwise no one will have any idea who you are or
|
|
what you are working on. You do not have to write a comprehensive
|
|
biography, just write a paragraph or two about who you are and
|
|
what you plan to be working on as a committer in FreeBSD. Email
|
|
this to <email>cvs-committers@FreeBSD.org</email> and you will be on
|
|
your way!</para>
|
|
|
|
<para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid>
|
|
and create yourself 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
|
|
to <replaceable>yourusername</replaceable>@FreeBSD.org
|
|
to be forwarded. 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>
|
|
|
|
<para>All new committers also have a mentor assigned to them for
|
|
the first few months. Your mentor is more or less responsible for
|
|
explaining anything which is confusing to you and is also
|
|
responsible for your actions during this initial period. If you
|
|
make a bogus commit, it is only going to embarrass your mentor
|
|
and you should probably make it a policy to pass at least your
|
|
first few commits by your mentor before committing it to the
|
|
repository.</para>
|
|
|
|
<para>All commits should go to <literal>-CURRENT</literal> first
|
|
before being merged to <literal>-STABLE</literal>. No major new
|
|
features or high-risk modifications should be made to the
|
|
<literal>-STABLE</literal> branch.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="developer.relations">
|
|
<title>Developer Relations</title>
|
|
|
|
<para>If you are working directly on your own code or on code
|
|
which is already well established as your responsibility, then
|
|
there is probably little need to check with other committers
|
|
before jumping in with a commit. If you see a bug in an area of
|
|
the system which is clearly orphaned (and there are a few such
|
|
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
|
|
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
|
|
<makevar>MAINTAINER</makevar> in the
|
|
<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
|
|
unanswered or the committer otherwise indicates a lack of
|
|
proprietary interest in the area affected, go ahead and commit
|
|
it.</para>
|
|
|
|
<para>If you are at all unsure about a commit for any reason in
|
|
general, have it reviewed by <literal>-hackers</literal> first
|
|
before committing. Better to have it flamed then and there
|
|
rather than when it is part of the CVS repository. If you do
|
|
happen to commit something which results in controversy
|
|
erupting, you may also wish to consider backing the change out
|
|
again until the matter is settled. Remember – with CVS we
|
|
can always change it back.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="gnats">
|
|
<title>GNATS</title>
|
|
|
|
<para>The FreeBSD Project utilizes
|
|
<application>GNATS</application> for tracking bugs and change
|
|
requests. Be sure that if you commit a fix or suggestion found
|
|
in a <application>GNATS</application> PR, you use
|
|
<command>edit-pr <replaceable>pr-number</replaceable></command>
|
|
on <hostid>freefall</hostid> to close it. It is also considered
|
|
nice if you take time to close any PRs associated with your
|
|
commits, if appropriate. Your can also make use of
|
|
&man.send-pr.1; yourself for proposing any change which you feel
|
|
should probably be made, pending a more extensive peer-review
|
|
first.</para>
|
|
|
|
<para>You can find out more about <application>GNATS</application>
|
|
at:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</ulink></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><ulink url="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</ulink></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><ulink url="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>&man.send-pr.1;</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="people">
|
|
<title>Who's Who</title>
|
|
|
|
<para>Besides Peter Wemm and John Polstra, the repository
|
|
meisters, there are other FreeBSD project members whom you will
|
|
probably get to know in your new role as a committer. Briefly,
|
|
and by no means all-inclusively, these are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>&a.asami;</term>
|
|
|
|
<listitem>
|
|
<para>Is the portsmeister, 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
|
|
administering code freezes before the releases.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.bde;</term>
|
|
|
|
<listitem>
|
|
<para>Is 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
|
|
is.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.dg;</term>
|
|
|
|
<listitem>
|
|
<para>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
|
|
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
|
|
necessary.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.jkh;</term>
|
|
|
|
<listitem>
|
|
<para>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
|
|
pending release status. If there is something you want
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.markm;</term>
|
|
<listitem>
|
|
<para>Mark is the CVS repository meister for the
|
|
international crypto repository kept on
|
|
<hostid>internat.FreeBSD.org</hostid> in South Africa.</para>
|
|
|
|
<para>Mark also oversees most of the crypto code; if you have
|
|
any crypto updates, please ask Mark first.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.steve;</term>
|
|
|
|
<listitem>
|
|
<para>Steve is unofficial maintainer of
|
|
<filename>/usr/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
|
|
Report-meister, along with &a.phk;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.brian;</term>
|
|
|
|
<listitem>
|
|
<para>Official maintainer of
|
|
<filename>/usr/bin/ppp</filename> and LPD.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.wollman;</term>
|
|
|
|
<listitem>
|
|
<para>If you need advice on obscure network internals or
|
|
aren't sure of some potential change to the networking
|
|
subsystem you have in mind, Garrett is someone to talk
|
|
to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="ssh.guide">
|
|
<title>SSH Quick-Start Guide</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>Update and install the ssh port in
|
|
<filename>/usr/ports/security/ssh</filename> (should be
|
|
version 1.2.25 or later).</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Make sure that you run &man.ssh-agent.1; before running
|
|
other applications. X users, for example, usually do this
|
|
from their <filename>.xsession</filename> or
|
|
<filename>.xinitrc</filename> file. See &man.ssh-agent.1;
|
|
for details.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Generate a key pair using &man.ssh-keygen.1;. The key
|
|
pair will wind up in the
|
|
<filename><envar>$HOME</envar>/.ssh</filename>
|
|
directory.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Copy your public key
|
|
(<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>)
|
|
into your <filename>authorized_keys</filename> file in your
|
|
home directory on <hostid>freefall</hostid>
|
|
(i.e.
|
|
<filename><envar>$HOME</envar>/.ssh/authorized_keys</filename>).
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>Now you should be able to use &man.ssh-add.1; for
|
|
authentication once per session. This will prompt you for
|
|
your private key's pass phrase, and then store it in your
|
|
authentication agent (&man.ssh-agent.1;) so that you won't
|
|
have to retype it over and over.</para>
|
|
|
|
<para>Test by doing something such as <command>ssh
|
|
freefall.FreeBSD.org ls /usr</command>.</para>
|
|
|
|
<para>For more information, see
|
|
<filename>/usr/ports/security/ssh</filename>, &man.ssh.1;,
|
|
&man.ssh-agent.1;, &man.scp.1;, and &man.ssh-keygen.1;.</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>The FreeBSD Committers' Big List of Rules</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Respect other committers.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Discuss any significant change <emphasis>before</emphasis>
|
|
committing.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect existing maintainers if listed
|
|
(<makevar>MAINTAINER</makevar> field in
|
|
<filename>Makefile</filename> or <filename>MAINTAINER</filename>
|
|
file in the top-level directory).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Never touch the repository directly. Ask a Repomeister.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any disputed change must be backed out pending resolution of
|
|
the dispute if requested by a maintainer or the Principal
|
|
Architect. Security related changes may override a maintainer's
|
|
wishes at the Security Officer's discretion.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes go to -current before -stable unless specifically
|
|
permitted by the release engineer or unless they're not applicable
|
|
to -current. Any non-trivial or non-urgent change which is
|
|
applicable should also be allowed to sit in -current for at least 3
|
|
days before merging so that it can be given sufficient testing. The
|
|
release engineer has the same authority over the -stable branch as
|
|
outlined for the Principal Architect in rule #5.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Don't fight in public with other committers; it looks bad. If
|
|
you must "strongly disagree" about something, do so only in
|
|
private.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect all code freezes and read the committers mailing list on
|
|
a timely basis so you know when a code freeze is in effect.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt on any procedure, ask first!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your changes before committing them.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>As noted, breaking some of these rules can be grounds for suspension
|
|
or, upon repeated offense, permanent removal of commit privileges.
|
|
Three or more members of core, or the Principal Architect and another
|
|
member of core acting in unison, have the power to temporarily suspend
|
|
commit privileges until <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
|
|
repository), a temporary suspension may also be done by the repository
|
|
meisters or any other member of core who may happen to be awake at the
|
|
time. Only core as a whole has the authority to suspend commit
|
|
privileges for any significant length of time or to remove them
|
|
permanently, the latter generally only being done after consultation
|
|
with committers. This rule does not exist to set core up as a bunch of
|
|
cruel dictators who can dispose of committers as casually as empty soda
|
|
cans, but to give the project a kind of safety fuse. If someone is
|
|
seriously out of control, it's important to be able to deal with this
|
|
immediately rather than be paralyzed by debate. In all cases, a
|
|
committer whose privileges are suspended or revoked is entitled to a
|
|
“hearing”, the total duration of the suspension being
|
|
determined at that time. A committer whose privileges are suspended may
|
|
also request a review of the decision after 30 days and every 30 days
|
|
thereafter (unless the total suspension period is less than 30 days). A
|
|
committer whose privileges have been revoked entirely may request a
|
|
review after a period of 6 months have elapsed. This review policy is
|
|
<emphasis>strictly informal</emphasis> and, in all cases, core reserves
|
|
the right to either act on or disregard requests for review if they feel
|
|
their original decision to be the right one.</para>
|
|
|
|
<para>In all other aspects of project operation, core is a subset of
|
|
committers and is bound by the <emphasis>same rules</emphasis>. Just
|
|
because someone is in core doesn't mean that they have special
|
|
dispensation to step outside of any of the lines painted here; core's
|
|
“special powers” only kick in when it acts as a group, not
|
|
on an individual basis. As individuals, we are all committers first and
|
|
core second.</para>
|
|
|
|
<sect2>
|
|
<title>Details</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Respect other committers.</para>
|
|
|
|
<para>This means that you need to treat other committers as the
|
|
peer-group developers that they are. Despite our occasional
|
|
attempts to prove the contrary, one doesn't get into committers by
|
|
being stupid and nothing rankles more than being treated that way
|
|
by one of your peers. Whether we always feel respect for one
|
|
another or not (and everyone has off days), we still have to
|
|
<emphasis>treat</emphasis> other committers with respect at all
|
|
times or the whole team structure rapidly breaks down.</para>
|
|
|
|
<para>Being able to work together long term is this project's
|
|
greatest asset, one far more important than any set of changes to
|
|
the code, and turning arguments about code into issues that affect
|
|
our long-term ability to work harmoniously together is just not
|
|
worth the trade-off by any conceivable stretch of the
|
|
imagination.</para>
|
|
|
|
<para>To comply with this rule, don't send email when you're angry
|
|
or otherwise behave in a manner which is likely to strike others
|
|
as needlessly confrontational. First calm down, then think about
|
|
how to communicate in the most effective fashion for convincing
|
|
the other person(s) that your side of the argument is correct,
|
|
don't just blow off some steam so you can feel better in the short
|
|
term at the cost of a long-term flame war. Not only is this very
|
|
bad “energy economics”, but repeated displays of
|
|
public aggression which impair our ability to work well together
|
|
will be dealt with severely by the project leadership and may
|
|
result in suspension or termination of your commit privileges.
|
|
That's never an option which the project's leadership enjoys in
|
|
the slightest, but unity comes first. No amount of code or good
|
|
advice is worth trading that away.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Discuss any significant change <emphasis>before</emphasis>
|
|
committing.</para>
|
|
|
|
<para>The CVS repository is not where changes should be initially
|
|
submitted for correctness or argued over, that should happen first
|
|
in the mailing lists and then committed only once something
|
|
resembling consensus has been reached. This doesn't mean that you
|
|
have to ask permission before correcting every obvious syntax
|
|
error or man page misspelling, simply that you should try to
|
|
develop a feel for when a proposed change isn't quite such a
|
|
no-brainer and requires some feedback first. People really don't
|
|
mind sweeping changes if the result is something clearly better
|
|
than what they had before, they just don't like being
|
|
<emphasis>surprised</emphasis> by those changes. The very best
|
|
way of making sure that you're on the right track is to have your
|
|
code reviewed by one or more other committers.</para>
|
|
|
|
<para>When in doubt, ask for review!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect existing maintainers if listed.</para>
|
|
|
|
<para>Many parts of FreeBSD aren't “owned” 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
|
|
first. One convention we use is to put a maintainer line in the
|
|
<filename>Makefile</filename> for any package or subtree which is
|
|
being actively maintained by one or more people; see <ulink
|
|
url="http://www.FreeBSD.org/handbook/policies.html">http://www.FreeBSD.org/handbook/policies.html</ulink>
|
|
for documentation on this. Where sections of code have several
|
|
maintainers, commits to affected areas by one maintainer need to
|
|
be reviewed by at least one other maintainer. In cases where the
|
|
<quote>maintainer-ship</quote> of something isn't clear, you can also look at
|
|
the CVS logs for the file(s) in question and see if someone has
|
|
been working recently or predominantly in that area.</para>
|
|
|
|
<para>Other areas of FreeBSD fall under the control of someone who
|
|
manages an overall category of FreeBSD evolution, such as
|
|
internationalization or networking. See
|
|
<ulink
|
|
url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.FreeBSD.org/handbook/staff-who.html</ulink> for more information on this.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Never touch the repository directly. Ask a
|
|
Repomeister.</para>
|
|
|
|
<para>This is pretty clear - you're not allowed to make direct
|
|
modifications to the CVS repository, period. In case of
|
|
difficulty, ask one of the repository meisters by sending mail to
|
|
<email>cvs@FreeBSD.org</email> and simply wait for them to fix the
|
|
problem and get back to you. Do not attempt to fix the problem
|
|
yourself!</para>
|
|
|
|
<para>If you're thinking about putting down a tag or doing a new
|
|
import of code on a vendor branch, you might also find it useful
|
|
to ask for advice first. A lot of people get this wrong the first
|
|
few times and the consequences are expensive in terms of files
|
|
touched and angry CVSup/CTM folks who are suddenly getting a lot
|
|
of changes sent over unnecessarily.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any disputed change must be backed out pending resolution of
|
|
the dispute if requested by a maintainer or the Principal
|
|
Architect. Security related changes may override a maintainer's
|
|
wishes at the Security Officer's discretion.</para>
|
|
|
|
<para>This may be hard to swallow in times of conflict (when each
|
|
side is convinced that they're in the right, of course) but CVS
|
|
makes it unnecessary to have an ongoing dispute raging when it's
|
|
far easier to simply reverse the disputed change, get everyone
|
|
calmed down again and then try and figure out how best to proceed.
|
|
If the change turns out to be the best thing after all, it can be
|
|
easily brought back. If it turns out not to be, then the users
|
|
didn't have to live with the bogus change in the tree while
|
|
everyone was busily debating its merits. People very very rarely
|
|
call for back-outs in the repository since discussion generally
|
|
exposes bad or controversial changes before the commit even
|
|
happens, but on such rare occasions the back-out should be done
|
|
without argument so that we can get immediately on to the topic of
|
|
figuring out whether it was bogus or not.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes go to -current before -stable unless specifically
|
|
permitted by the release engineer or unless they're not applicable
|
|
to -current. Any non-trivial or non-urgent change which is
|
|
applicable should also be allowed to sit in -current for at least
|
|
3 days before merging so that it can be given sufficient testing.
|
|
The release engineer has the same authority over the -stable
|
|
branch as outlined in rule #5.</para>
|
|
|
|
<para>This is another <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
|
|
be overly conservative to the casual observer, but also bear in
|
|
mind the fact that conservatism is supposed to be the hallmark of
|
|
-stable and different rules apply there than in -current. There's
|
|
also really no point in having -current be a testing ground if
|
|
changes are merged over from -stable immediately without giving
|
|
them a chance be tested by the -current developers, so allow some
|
|
time to elapse before merging unless the -stable fix is critical,
|
|
time sensitive or so obvious as to make further testing
|
|
unnecessary (spelling fixes to manpages, obvious bug/typo fixes,
|
|
etc.) In other words, apply common sense.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Don't fight in public with other committers; it looks bad. If
|
|
you must “strongly disagree” about something, do so
|
|
only in private.</para>
|
|
|
|
<para>This project has a public image to uphold and that image is
|
|
very important to all of us, especially if we're to continue to
|
|
attract new members. There will be occasions when, despite
|
|
everyone's very best attempts at self-control, tempers are lost
|
|
and angry words are exchanged, and the best we can do is try and
|
|
minimize the effects of this until everyone has cooled back down.
|
|
That means that you shouldn't air your angry words in public and
|
|
you shouldn't forward private correspondence to public mailing
|
|
lists or aliases. What people say one-to-one is often much less
|
|
sugar-coated than what they'd say in public, and such
|
|
communications therefore have no place there - they only serve to
|
|
inflame an already bad situation. If the person sending you a
|
|
flame-o-gram had at least the grace to send it privately, then
|
|
have the grace to keep it private yourself. If you feel you're
|
|
being unfairly treated by another developer and it's causing you
|
|
anguish, bring the matter up with core rather than taking it
|
|
public. We'll do our best to play peace makers and get things
|
|
back to sanity. In cases where the dispute involves a change to
|
|
the codebase and the participants don't appear to be reaching an
|
|
amicable agreement, core may appoint a mutually-agreeable 3rd
|
|
party to resolve the dispute. All parties involved must then
|
|
agree to be bound by the decision reached by this 3rd
|
|
party.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect all code freezes and read the committers mailing list
|
|
on a timely basis so you know when they are.</para>
|
|
|
|
<para>Committing changes during a code freeze is a really big
|
|
mistake and committers are expected to keep up-to-date on what's
|
|
going on before jumping in after a long absence and committing 10
|
|
megabytes worth of accumulated stuff. People who abuse this on a
|
|
regular basis will have their commit privileges suspended until
|
|
they get back from the FreeBSD Happy Reeducation Camp we run in
|
|
Greenland.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt on any procedure, ask first!</para>
|
|
|
|
<para>So many mistakes are made because someone's in a hurry and
|
|
just assumes they know the right way of going about something. If
|
|
you haven't done it before, chances are good that you don't
|
|
actually know the way we do things and really need to ask first or
|
|
you're going to completely embarrass yourself in public. There's
|
|
no shame in asking “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>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your changes before committing them.</para>
|
|
|
|
<para>This may sound obvious, but if it really were so obvious then
|
|
we probably wouldn't see so many cases of people clearly not doing
|
|
this. If your changes are to the kernel, make sure you can still
|
|
compile both GENERIC and LINT. If your changes are anywhere else,
|
|
make sure you can still make world. If your changes are to a
|
|
branch, make sure your testing occurs with a machine which is
|
|
running that code. If you have a change which also may break
|
|
another architecture, be sure and test on all supported
|
|
architectures. Currently, this is only the x86 and the alpha so
|
|
it's pretty easy to do. If you need to test on the AXP, your
|
|
account on <hostid role="fqdn">beast.FreeBSD.org</hostid> will let
|
|
you compile and test alpha binaries/kernels/etc. As other
|
|
architectures are added to the FreeBSD supported platforms list,
|
|
the appropriate shared testing resources will be made
|
|
available.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Other Suggestions</title>
|
|
|
|
<para>When committing documentation changes, also be sure and use a
|
|
spell checker before committing. :) For all SGML docs, you should
|
|
also verify that your formatting directives are correct by running
|
|
<command>make lint</command>.</para>
|
|
|
|
<para>For all on-line manual pages, run <command>manck</command> (from ports) over the
|
|
man page to verify the all of the cross references and file references
|
|
are correct and that the man page has all of the appropriate
|
|
<makevar>MLINK</makevar>s installed.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Ports Specific FAQ</title>
|
|
|
|
<qandaset>
|
|
<qandadiv>
|
|
<title>Importing a New Port</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I import a new port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, please read the section about repository
|
|
copy.</para>
|
|
|
|
<para>To import a new port, the easiest way 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
|
|
file. It was written by &a.joerg; so please send mail
|
|
to him if you have questions about
|
|
<command>easy-import</command>.</para>
|
|
|
|
<para>One thing it will not do for you is add the port to
|
|
the parent (category) <filename>Makefile</filename>.
|
|
You have to do that yourself.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Any other things I need to know when I import a new
|
|
port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Check the port, preferably to make sure it compiles
|
|
and packages correctly. This is the recommended
|
|
sequence:</para>
|
|
|
|
<screen>&prompt.user; <userinput>make install</userinput>
|
|
&prompt.user; <userinput>make package</userinput>
|
|
&prompt.user; <userinput>make deinstall</userinput>
|
|
&prompt.user; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput>
|
|
&prompt.user; <userinput>make deinstall</userinput>
|
|
&prompt.user; <userinput>make reinstall</userinput>
|
|
&prompt.user; <userinput>make package</userinput>
|
|
</screen>
|
|
|
|
<para>The Handbook's
|
|
<ulink url="../handbook/porting.html">porting
|
|
section</ulink> contains more detailed
|
|
instructions.</para>
|
|
|
|
<para>Use &man.portlint.1; to check the syntax of the port.
|
|
You don't necessarily have to eliminate all warnings but
|
|
make sure you have fixed the simple ones.</para>
|
|
|
|
<para>If the port came from a submitter who has not
|
|
contributed to the project before, add that person's
|
|
name to the Handbook's
|
|
<citetitle pubwork="section">Additional Contributors</citetitle>
|
|
section.</para>
|
|
|
|
<para>Close the PR if the port came in as a PR. To close
|
|
a PR, just do
|
|
<userinput>edit-pr <replaceable>PR#</replaceable></userinput>
|
|
on <hostid>freefall</hostid> and change the
|
|
<varname>state</varname> from <constant>open</constant>
|
|
to <constant>closed</constant>. You will be asked to
|
|
enter a log message and then you are done.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Repository Copies</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>When do we need a repository copy?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>When you want to import a port that is related to
|
|
any port that is already in the tree in a separate
|
|
directory, please send mail to the ports manager asking
|
|
about it. Here <wordasword>related</wordasword> means
|
|
it is a different version or a slightly modified
|
|
version. Examples are
|
|
<filename>print/ghostscript*</filename> (different
|
|
versions) and <filename>x11-wm/windowmaker*</filename>
|
|
(English-only and internationalized version).</para>
|
|
|
|
<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
|
|
descendant of a port already in a tree.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>When do we <emphasis>not</emphasis> need a
|
|
repository copy?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>When there is no history to preserve. If a port is
|
|
imported into a wrong category and is moved immediately,
|
|
it suffices to simply <command>cvs remove</command> the
|
|
old one and <command>cvs import</command> the new
|
|
one.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What do I need to do?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Send mail to the ports manager, who will do a copy
|
|
from the old location/name to the new location/name.
|
|
You will then get a notice, at which point you are
|
|
expected to perform the following:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para><command>cvs remove</command> the old port (if
|
|
necessary)</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Adjust the parent (category)
|
|
<filename>Makefile</filename></para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Update <filename>CVSROOT/modules</filename></para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If other ports depend on the updated port,
|
|
change their <filename>Makefile</filename>s'
|
|
dependency lines</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If the port changed categories, modify the
|
|
<makevar>CATEGORIES</makevar> line of the port's
|
|
<filename>Makefile</filename> accordingly</para>
|
|
</step>
|
|
</procedure>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Ports Freeze</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What is a <quote>ports freeze</quote>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Before a release, it is necessary to restrict
|
|
commits to the ports tree for a short period of time
|
|
while the packages and the release itself are being
|
|
built. This is to ensure consistency among the various
|
|
parts of the release, and is called the <quote>ports
|
|
freeze</quote>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How long is a ports freeze?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Usually two to three days.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What does it mean to me?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>During the ports freeze, you are not allowed to
|
|
commit anything to the tree without explicit approval
|
|
from the ports manager. <quote>Explicit
|
|
approval</quote> here means either of the
|
|
following:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You asked the ports manager and got a reply
|
|
saying, <quote>Go ahead and commit
|
|
it.</quote></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The ports manager sent a mail to you or the
|
|
mailing lists during the ports freeze pointing out
|
|
that the port is broken and has to be fixed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Note that you do not have implicit permission to fix
|
|
a port during the freeze just because it is
|
|
broken.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know when the ports freeze starts?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>The ports manager will send out warning messages to
|
|
the <email>freebsd-ports@FreeBSD.org</email> and
|
|
<email>cvs-committers@FreeBSD.org</email> mailing lists announcing
|
|
the start of the impending release, usually two or three
|
|
weeks in advance. The exact starting time will not be
|
|
determined until a few days before the actual release.
|
|
This is because the ports freeze has to be synchronized
|
|
with the release, and it is usually not known until then
|
|
when exactly the release will be rolled.</para>
|
|
|
|
<para>When the freeze starts, there will be another
|
|
announcement to the <email>cvs-committers@FreeBSD.org</email>
|
|
list, of course.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know when the ports freeze ends?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>A few hours after the release, the ports manager
|
|
will send out a mail to the
|
|
<email>freebsd-ports@FreeBSD.org</email> and
|
|
<email>cvs-committers@FreeBSD.org</email> mailing lists
|
|
announcing the end of the ports freeze. Note that the
|
|
release being cut does not automatically end the freeze.
|
|
We have to make sure there will not be any last minute
|
|
snafus that result in an immediate re-rolling of the
|
|
release.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Miscellaneous Questions</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know if my port is building correctly or
|
|
not?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, go check
|
|
<ulink url="http://bento.FreeBSD.org/~asami/errorlogs/">http://bento.FreeBSD.org/~asami/errorlogs/</ulink>.
|
|
|
|
There you will find error logs from the latest package
|
|
building runs on 3-stable and 4-current.</para>
|
|
|
|
<para>However, just because the port doesn't show up there
|
|
doesn't mean it's building correctly. (One of the
|
|
dependencies may have failed, for instance.) Here are
|
|
the relevant directories on bento, so feel free to dig
|
|
around.</para>
|
|
|
|
<programlisting> /a/asami/portbuild/3/errors error logs from latest 3-stable run
|
|
/logs all logs from latest 3-stable run
|
|
/packages packages from latest 3-stable run
|
|
/bak/errors error logs from last complete 3-stable run
|
|
/bak/logs all logs from last complete 3-stable run
|
|
/bak/packages packages from last complete 3-stable run
|
|
/4/errors error logs from latest 4-current run
|
|
/logs all logs from latest 4-current run
|
|
/packages packages from latest 4-current run
|
|
/bak/errors error logs from last complete 4-current run
|
|
/bak/logs all logs from last complete 4-current run
|
|
/bak/packages packages from last complete 4-current run
|
|
</programlisting>
|
|
|
|
<para>Basically, if the port shows up in
|
|
<filename>packages</filename>, or it is in
|
|
<filename>logs</filename> but not in
|
|
<filename>errors</filename>, it built fine. (The
|
|
<filename>errors</filename> directories are what you get
|
|
from the web page.)</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>I added a new port. Do I need to add it to the
|
|
<filename>INDEX</filename>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>No. The ports manager will regenerate the
|
|
<filename>INDEX</filename> and commit it every few
|
|
days.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Are there any other files I'm not allowed to
|
|
touch?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Any file right 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
|
|
wra(i)th.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
</qandaset>
|
|
</sect1>
|
|
</article>
|