Merge the ports committers' guide into the new committers' guide.

Reviewed by:	nik
This commit is contained in:
John Baldwin 1999-09-29 02:12:37 +00:00
parent c2f66c7ff1
commit a54d72c628
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=5763
2 changed files with 680 additions and 0 deletions

View file

@ -772,4 +772,344 @@
<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</email> and
<email>cvs-committers</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</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</email>
and <email>cvs-committers</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>

View file

@ -772,4 +772,344 @@
<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</email> and
<email>cvs-committers</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</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</email>
and <email>cvs-committers</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>