svn commit: r45617 - head/en_US.ISO8859-1/books/porters-handbook/upgrading
Mathieu Arnold
mat at FreeBSD.org
Tue Sep 16 12:02:19 UTC 2014
Author: mat (ports committer)
Date: Tue Sep 16 12:02:19 2014
New Revision: 45617
URL: http://svnweb.freebsd.org/changeset/doc/45617
Log:
igor -Ry and some other rewording and fixes.
Differential Revision: https://reviews.freebsd.org/D655
Reviewed by: wblock
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Tue Sep 16 12:01:29 2014 (r45616)
+++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Tue Sep 16 12:02:19 2014 (r45617)
@@ -11,29 +11,32 @@
<title>Upgrading a Port</title>
- <para>When you notice that a port is out of date compared to the
- latest version from the original authors, you should first ensure
- that you have the latest port. You can find them in the
- <filename>ports/ports-current</filename> directory of the &os; FTP
- mirror sites. However, if you are working with more than a few
- ports, you will probably find it easier to use
- <application>Subversion</application> or &man.portsnap.8; to keep
- your whole ports collection up-to-date, as described in the <link
+ <para>When a port is not the most recent version available from the
+ authors, update the local working copy of
+ <filename>/usr/ports</filename>. The port might have already been
+ updated to the new version.</para>
+
+ <para>When working with more than a few ports, it will probably be
+ easier to use <application>Subversion</application> to keep
+ the whole ports collection up-to-date, as described in the <link
xlink:href="&url.books.handbook;/ports-using.html">Handbook</link>.
This will have the added benefit of tracking all the port's
dependencies.</para>
<para>The next step is to see if there is an update already pending.
- To do this, you have two options. There is a searchable interface
+ To do this, there are two options. There is a searchable interface
to the <link
- xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">FreeBSD
- Problem Report (PR) database</link> (also known as
- <literal>GNATS</literal>). Select <literal>ports</literal> in
- the dropdown, and enter the name of the port.</para>
+ xlink:href="https://bugs.freebsd.org/search/">FreeBSD
+ Problem Report (PR) or bug database</link>.
+ Select <literal>Ports Tree</literal> in
+ the <literal>Product</literal> dropdown, and enter the name of the port in the
+ <literal>Summary</literal> field.</para>
<para>However, sometimes people forget to put the name of the port
- into the Synopsis field in an unambiguous fashion. In that
- case, you can try the
+ into the Summary field in an unambiguous fashion. In that
+ case, try searching in the <literal>Comment</literal> field in
+ the <literal>Detailled Bug Information</literal> section, or try
+ the
<link linkend="portsmon">&os; Ports Monitoring System</link>
(also known as <literal>portsmon</literal>). This system
attempts to classify port PRs by portname. To search for PRs
@@ -46,32 +49,32 @@
<command>make maintainer</command>. That person may already be
working on an upgrade, or have a reason to not upgrade the port
right now (because of, for example, stability problems of the
- new version); you would not want to duplicate their work. Note
+ new version), and there is no need to duplicate their work. Note
that unmaintained ports are listed with a maintainer of
<literal>ports at FreeBSD.org</literal>, which is just the general
ports mailing list, so sending mail there probably will not help
in this case.</para>
<para>If the maintainer asks you to do the upgrade or there is
- no maintainer, then you have a chance to help out &os; by
- preparing the update yourself! Please do this by using the
+ no maintainer, then help out &os; by
+ preparing the update! Please do this by using the
&man.diff.1; command in the base system.</para>
<para>To create a suitable <command>diff</command> for a single
patch, copy the file that needs patching to
- <replaceable>something.orig</replaceable>, save your changes to
- <replaceable>something</replaceable> and then create your
+ <filename><replaceable>something</replaceable>.orig</filename>, save the changes to
+ <filename><replaceable>something</replaceable></filename> and then create the
patch:</para>
<informalexample>
- <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen>
+ <screen>&prompt.user; <userinput>diff -u <replaceable>something</replaceable>.orig <replaceable>something</replaceable> > something.diff</userinput></screen>
</informalexample>
- <para>Otherwise, you should either use the
+ <para>Otherwise, either use the
<command>svn diff</command> method (<xref linkend="svn-diff"/>)
or copy the contents of the port to an entire different
directory and use the result of the recursive &man.diff.1;
- output of the new and old ports directories (e.g., if your
+ output of the new and old ports directories (for example, if the
modified port directory is called <filename>superedit</filename>
and the original is in our tree as
<filename>superedit.bak</filename>, then save the result of
@@ -82,16 +85,19 @@
deal with the case of new files being added or old files being
deleted. Before sending us the diff, please examine the output
to make sure all the changes make sense. (In particular, make
- sure you first clean out the work directories with
+ sure to first clean out the work directories with
<command>make clean</command>).</para>
- <para>To simplify common operations with patch files, you can use
+ <para>To simplify common operations with patch files, use
+ <command>make makepatch</command> as described in <xref
+ linkend="slow-patch"/>.
+ Other tools exists, like
<filename>/usr/ports/Tools/scripts/patchtool.py</filename>.
Before using it, please read
<filename>/usr/ports/Tools/scripts/README.patchtool</filename>.</para>
<para>If the port is unmaintained, and you are actively using
- it yourself, please consider volunteering to become its
+ it, please consider volunteering to become its
maintainer. &os; has over 4000 ports without maintainers, and
this is an area where more volunteers are always needed. (For a
detailed description of the responsibilities of maintainers,
@@ -99,20 +105,19 @@
xlink:href="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER">Developer's
Handbook</link>.)</para>
- <para>The best way to send us the diff is by including it via
- &man.send-pr.1; (category <literal>ports</literal>). If you are
+ <para>To submit the diff, use the <link
+ xlink:href="https://bugs.freebsd.org/submit/">bug submit
+ form</link> (category <literal>Ports Tree</literal>). If the
+ submitter is also
maintaining the port, be sure to put <literal>[maintainer
- update]</literal> at the beginning of your synopsis line and set
- the <quote>Class</quote> of your PR to
- <literal>maintainer-update</literal>. Otherwise, the
- <quote>Class</quote> of your PR should be
- <literal>change-request</literal>. Please mention any added or
+ update]</literal> at the beginning of the
+ <literal>Summary</literal> line.
+ Please mention any added or
deleted files in the message, as they have to be explicitly
- specified to &man.svn.1; when doing a commit. If the diff is
- more than about 20KB, please compress and uuencode it;
- otherwise, just include it in the PR as is.</para>
+ specified to &man.svn.1; when doing a commit. Do not compress or
+ encode the diff.</para>
- <para>Before using &man.send-pr.1;, review the <link
+ <para>Before submitting the bug, review the <link
xlink:href="&url.articles.problem-reports;/pr-writing.html">
Writing the problem report</link> section in the Problem
Reports article. It contains far more information about how to
@@ -134,7 +139,7 @@
committers understand exactly what is being changed.</para>
</note>
- <para>Now that you have done all that, read about
+ <para>Now that all of that is done, read about
how to keep up-to-date in <xref linkend="keeping-up"/>.</para>
<sect1 xml:id="svn-diff">
@@ -145,8 +150,8 @@
are easier to handle than diffs between
<quote>new and old</quote> directories. It is easier
to see what has changed, and to update the diff if
- something was modified in the Ports Collection since you
- began work on it, or if the
+ something was modified in the Ports Collection since the
+ work on it began, or if the
committer asks for something to be fixed. Also, a patch
generated with <command>svn diff</command> can be easily applied
with <command>svn patch</command> and will save some time to the
@@ -159,7 +164,7 @@
<calloutlist>
<callout arearefs="my-wrkdir">
- <para>This can be anywhere you want, of course; building
+ <para>This can be anywhere, of course. Building
ports is not limited to within
<filename>/usr/ports/</filename>.</para>
</callout>
@@ -175,15 +180,15 @@
</callout>
</calloutlist>
- <para>While in the working directory, make any changes that you
- would usually make to the port. If you add, move or remove a
+ <para>While in the port directory, make any changes that are
+ needed. If adding, moving, or removing a
file, use <command>svn</command> to track these changes:</para>
- <screen>&prompt.user; <userinput>svn add new_file</userinput>
-&prompt.user; <userinput>svn move old_name new_name</userinput>
-&prompt.user; <userinput>svn remove deleted_file</userinput></screen>
+ <screen>&prompt.user; <userinput>svn add <replaceable>new_file</replaceable></userinput>
+&prompt.user; <userinput>svn move <replaceable>old_name</replaceable> <replaceable>new_name</replaceable></userinput>
+&prompt.user; <userinput>svn remove <replaceable>deleted_file</replaceable></userinput></screen>
- <para>Make sure that you check the port using the checklist in
+ <para>Make sure to check the port using the checklist in
<xref linkend="porting-testing"/> and
<xref linkend="porting-portlint"/>.</para>
@@ -192,8 +197,8 @@
<calloutlist>
<callout arearefs="svn-update">
- <para>This will try to merge the differences between your
- patch and current repository version; watch the output
+ <para>This will attempt to merge the differences between the
+ patch and current repository version. Watch the output
carefully. The letter in front of each file name
indicates what was done with it. See
<xref linkend="table-svn-up"/> for a complete list.</para>
@@ -213,8 +218,8 @@
<row>
<entry>G</entry>
- <entry>The file was updated without problems (you will
- only see this when working against a remote
+ <entry>The file was updated without problems (only when
+ working against a remote
repository).</entry>
</row>
@@ -239,40 +244,41 @@
&man.svn.1; was not able to merge the local changes with those
from the repository. It is always a good idea to inspect the
changes anyway, since &man.svn.1; does not know anything about
- how a port should be, so it might (and probably will) merge
+ the structure of a port, so it might (and probably will) merge
things that do not make sense.</para>
<para>The last step is to make a unified &man.diff.1;
of the changes:</para>
- <screen>&prompt.user; <userinput>svn diff > ../`basename ${PWD}`.diff</userinput></screen>
+ <screen>&prompt.user; <userinput>svn diff > ../`make -VPKGNAME`.diff</userinput></screen>
<note>
- <para>Any files that have been removed should be explicitly
+ <para>Any files that have been removed have to be explicitly
mentioned in the PR, because file removal may not be obvious
to the committer.</para>
</note>
- <para>Send your patch following the guidelines in
+ <para>Send the patch following the guidelines in
<xref linkend="port-upgrading"/>.</para>
<tip>
- <para>You can have patch automatically generated and the PR
- pre-filled with your contact information by using
- the <application>Port Tools</application> <command>port
- submit</command> command. See <xref
+ <para>The patch can be automatically generated and the PR
+ pre-filled with the contact information by using
+ <command>port submit</command>. See <xref
linkend="testing-porttools"/> for more details.</para>
</tip>
</sect1>
<sect1 xml:id="moved-and-updating-files">
- <title>The Files <filename>UPDATING</filename> and
+ <title><filename>UPDATING</filename> and
<filename>MOVED</filename></title>
+ <sect2 xml:id="moved-and-updating-updating">
+ <title><filename>/usr/ports/UPDATING</filename></title>
+
<para>If upgrading the port requires special steps like
changing configuration files or running a specific program,
- you should document this in the file
- <filename>/usr/ports/UPDATING</filename>. The format of
+ it must be documented in this file. The format of
an entry in this file is as follows:</para>
<programlisting>YYYYMMDD:
@@ -281,22 +287,42 @@
Special instructions</programlisting>
- <para>If you are including exact portmaster or portupgrading
- instructions, please make sure to get the shell escaping
- right.</para>
+ <tip>
+ <para>When including exact
+ <application>portmaster</application>,
+ <application>portupgrade</application>, and/or
+ <application>pkg</application> instructions, please make sure
+ to get the shell escaping right. For example, do
+ <emphasis>not</emphasis> use:</para>
+
+ <screen>&prompt.root; <userinput>pkg delete -g -f docbook-xml* docbook-sk* docbook[2345]??-* docbook-4*</userinput></screen>
+
+ <para>As shown, the command will only work with
+ <application>bourne shells</application>. Instead, use the
+ form shown below, which will work with both
+ <application>bourne shell</application> and
+ <application>c-shell</application>:</para>
+
+ <screen>&prompt.root; <userinput>pkg delete -g -f docbook-xml\* docbook-sk\* docbook\[2345\]\?\?-\* docbook-4\*</userinput></screen>
+ </tip>
<note>
<para>It is recommended that the AFFECTS line contains a glob
matching all the ports affected by the entry so that automated
tools can parse it as easily as possible. If an update
concerns all the existing <application>BIND 9</application>
- versions the <literal>AFFECTS</literal> content should be
- <literal>users of dns/bind9*</literal>, it should
+ versions the <literal>AFFECTS</literal> content must be
+ <literal>users of dns/bind9*</literal>, it must
<emphasis>not</emphasis> be <literal>users of BIND
9</literal></para>
</note>
- <para>The <filename>/usr/ports/MOVED</filename> file is used to
+ </sect2>
+
+ <sect2 xml:id="moved-and-updating-moved">
+ <title><filename>/usr/ports/MOVED</filename></title>
+
+ <para>This file is used to
list moved or removed ports. Each line in the file is made
up of the name of the port, where the port was moved to, when,
and why. If the port was removed, the section detailing where
@@ -306,22 +332,32 @@
<programlisting>old name|new name (blank for deleted)|date of move|reason</programlisting>
- <para>The date should be entered in the form
- <literal>YYYY-MM-DD</literal>. New entries should be added to
- the top of the file to keep it in reverse chronological order
- (the latest entries first).</para>
+ <para>The date must be entered in the form
+ <literal>YYYY-MM-DD</literal>. New entries are added to
+ the top of the file to keep it in reverse chronological order,
+ with the last entry first.</para>
<para>If a port was removed but has since been restored,
delete the line in this file that states that it was
removed.</para>
<para>If a port was renamed and then renamed back to its original
- name, you should add a new one with the intermediate name to the
+ name, add a new one with the intermediate name to the
old name, and remove the old entry as to not create a
loop.</para>
- <para>The changes can be validated with
- <command>Tools/scripts/MOVEDlint.awk</command>.</para>
+ <note>
+ <para>Any changes must be validated with
+ <command>Tools/scripts/MOVEDlint.awk</command>.</para>
+
+ <para>If using a ports directory other than <filename>/usr/ports</filename>, use:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>cd <replaceable>/home/user/ports</replaceable></userinput>
+&prompt.user; <userinput>env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk</userinput></screen>
+ </informalexample>
+ </note>
+ </sect2>
</sect1>
</chapter>
More information about the svn-doc-all
mailing list