svn commit: r43842 - head/en_US.ISO8859-1/books/porters-handbook/upgrading
Warren Block
wblock at FreeBSD.org
Sun Feb 9 02:36:59 UTC 2014
Author: wblock
Date: Sun Feb 9 02:36:59 2014
New Revision: 43842
URL: http://svnweb.freebsd.org/changeset/doc/43842
Log:
Whitespace-only fixes, translators please ignore.
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 Sun Feb 9 02:03:11 2014 (r43841)
+++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Sun Feb 9 02:36:59 2014 (r43842)
@@ -5,293 +5,294 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="port-upgrading">
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="port-upgrading">
+
+ <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
+ 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 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>
+
+ <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
+ <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
+ about a particular port, use the <link
+ xlink:href="http://portsmon.FreeBSD.org/portoverview.py">Overview
+ of One Port</link>.</para>
+
+ <para>If there is no pending PR, the next step is to send an email
+ to the port's maintainer, as shown by
+ <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
+ 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
+ &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
+ patch:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen>
+ </informalexample>
+
+ <para>Otherwise, you should 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
+ 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
+ <command>diff -ruN superedit.bak superedit</command>). Either
+ unified or context diff is fine, but port committers generally
+ prefer unified diffs. Note the use of the <literal>-N</literal>
+ option—this is the accepted way to force diff to properly
+ 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
+ <command>make clean</command>).</para>
+
+ <para>To simplify common operations with patch files, you can use
+ <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
+ 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,
+ refer to the section in the <link
+ 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
+ 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
+ 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>
+
+ <para>Before using &man.send-pr.1;, 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
+ write useful problem reports.</para>
+
+ <important>
+ <para>If the upgrade is motivated by security concerns or a
+ serious fault in the currently committed port, please notify
+ the &a.portmgr; to request immediate rebuilding and
+ redistribution of the port's package. Unsuspecting users
+ of <command>pkg</command> will otherwise continue to install
+ the old version via <command>pkg install</command> for several
+ weeks.</para>
+ </important>
+
+ <note>
+ <para>Once again, please use &man.diff.1; and not &man.shar.1;
+ to send updates to existing ports! This helps ports
+ committers understand exactly what is being changed.</para>
+ </note>
+
+ <para>Now that you have done all that, read about
+ how to keep up-to-date in <xref linkend="keeping-up"/>.</para>
+
+ <sect1 xml:id="svn-diff">
+ <title>Using <application>Subversion</application> to Make
+ Patches</title>
+
+ <para>When possible, please submit a &man.svn.1; diff. They
+ 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
+ committer asks for something to be fixed.</para>
- <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
- 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 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>
-
- <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
- <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
- about a particular port, use the <link
- xlink:href="http://portsmon.FreeBSD.org/portoverview.py">Overview
- of One Port</link>.</para>
-
- <para>If there is no pending PR, the next step is to send an email
- to the port's maintainer, as shown by
- <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
- 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
- &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
- patch:</para>
-
- <informalexample>
- <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen>
- </informalexample>
-
- <para>Otherwise, you should 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
- 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
- <command>diff -ruN superedit.bak superedit</command>). Either
- unified or context diff is fine, but port committers generally
- prefer unified diffs. Note the use of the <literal>-N</literal>
- option—this is the accepted way to force diff to properly
- 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
- <command>make clean</command>).</para>
-
- <para>To simplify common operations with patch files, you can use
- <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
- 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,
- refer to the section in the <link
- 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
- 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
- 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>
-
- <para>Before using &man.send-pr.1;, 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
- write useful problem reports.</para>
-
- <important>
- <para>If the upgrade is motivated by security concerns or a
- serious fault in the currently committed port, please notify
- the &a.portmgr; to request immediate rebuilding and
- redistribution of the port's package. Unsuspecting users
- of <command>pkg</command> will otherwise continue to install
- the old version via <command>pkg install</command> for several
- weeks.</para>
- </important>
-
- <note>
- <para>Once again, please use &man.diff.1; and not &man.shar.1;
- to send updates to existing ports! This helps ports
- committers understand exactly what is being changed.</para>
- </note>
-
- <para>Now that you have done all that, read about
- how to keep up-to-date in <xref linkend="keeping-up"/>.</para>
-
- <sect1 xml:id="svn-diff">
- <title>Using <application>Subversion</application> to Make
- Patches</title>
-
- <para>When possible, please submit a &man.svn.1; diff. They
- 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
- committer asks for something to be fixed.</para>
-
- <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co xml:id="my-wrkdir"/>
+ <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co xml:id="my-wrkdir"/>
&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd</userinput> <co xml:id="svn-FreeBSD-org"/>
&prompt.user; <userinput>cd ~/my_wrkdir/pdnsd</userinput></screen>
- <calloutlist>
- <callout arearefs="my-wrkdir">
+ <calloutlist>
+ <callout arearefs="my-wrkdir">
- <para>This can be anywhere you want, of course; building
- ports is not limited to within
- <filename>/usr/ports/</filename>.</para>
- </callout>
-
- <callout arearefs="svn-FreeBSD-org">
- <para><link
- xlink:href="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</link>
- is a public <application>Subversion</application> server.
- Select the closest mirror and verify the mirror server
- certificate from the list of <link
- xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
- mirror sites</link>.</para>
- </callout>
- </calloutlist>
-
- <para>While in the working directory, make any changes that you
- would usually make to the port. If you add or remove a file,
- use <command>svn</command> to track these changes:</para>
+ <para>This can be anywhere you want, of course; building
+ ports is not limited to within
+ <filename>/usr/ports/</filename>.</para>
+ </callout>
+
+ <callout arearefs="svn-FreeBSD-org">
+ <para><link
+ xlink:href="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</link>
+ is a public <application>Subversion</application> server.
+ Select the closest mirror and verify the mirror server
+ certificate from the list of <link
+ xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
+ mirror sites</link>.</para>
+ </callout>
+ </calloutlist>
+
+ <para>While in the working directory, make any changes that you
+ would usually make to the port. If you add or remove a file,
+ use <command>svn</command> to track these changes:</para>
- <screen>&prompt.user; <userinput>svn add new_file</userinput>
+ <screen>&prompt.user; <userinput>svn add new_file</userinput>
&prompt.user; <userinput>svn remove deleted_file</userinput></screen>
- <para>Make sure that you check the port using the checklist in
- <xref linkend="porting-testing"/> and
- <xref linkend="porting-portlint"/>.</para>
+ <para>Make sure that you check the port using the checklist in
+ <xref linkend="porting-testing"/> and
+ <xref linkend="porting-portlint"/>.</para>
- <screen>&prompt.user; <userinput>svn status</userinput>
+ <screen>&prompt.user; <userinput>svn status</userinput>
&prompt.user; <userinput>svn update</userinput> <co xml:id="svn-update"/></screen>
- <calloutlist>
- <callout arearefs="svn-update">
- <para>This will try to merge the differences between your
- 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>
- </callout>
- </calloutlist>
-
- <table pgwide="1" frame="none" xml:id="table-svn-up">
- <title><application>Subversion</application> Update File
- Prefixes</title>
-
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>U</entry>
- <entry>The file was updated without problems.</entry>
- </row>
-
- <row>
- <entry>G</entry>
- <entry>The file was updated without problems (you will
- only see this when working against a remote
- repository).</entry>
- </row>
-
- <row>
- <entry>M</entry>
- <entry>The file had been modified, and was merged
- without conflicts.</entry>
- </row>
-
- <row>
- <entry>C</entry>
- <entry>The file had been modified, and was merged with
- conflicts.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>If <literal>C</literal> is displayed as a result of
- <command>svn update</command>, it means something changed in
- the <application>Subversion</application> repository and
- &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
- 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>
-
- <note>
- <para>Any files that have been removed should 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
- <xref linkend="port-upgrading"/>.</para>
- </sect1>
-
- <sect1 xml:id="moved-and-updating-files">
- <title>The Files <filename>UPDATING</filename> and
- <filename>MOVED</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
- an entry in this file is as follows:</para>
+ <calloutlist>
+ <callout arearefs="svn-update">
+ <para>This will try to merge the differences between your
+ 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>
+ </callout>
+ </calloutlist>
+
+ <table pgwide="1" frame="none" xml:id="table-svn-up">
+ <title><application>Subversion</application> Update File
+ Prefixes</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>U</entry>
+ <entry>The file was updated without problems.</entry>
+ </row>
+
+ <row>
+ <entry>G</entry>
+ <entry>The file was updated without problems (you will
+ only see this when working against a remote
+ repository).</entry>
+ </row>
+
+ <row>
+ <entry>M</entry>
+ <entry>The file had been modified, and was merged
+ without conflicts.</entry>
+ </row>
+
+ <row>
+ <entry>C</entry>
+ <entry>The file had been modified, and was merged with
+ conflicts.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>If <literal>C</literal> is displayed as a result of
+ <command>svn update</command>, it means something changed in
+ the <application>Subversion</application> repository and
+ &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
+ 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>
+
+ <note>
+ <para>Any files that have been removed should 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
+ <xref linkend="port-upgrading"/>.</para>
+ </sect1>
+
+ <sect1 xml:id="moved-and-updating-files">
+ <title>The Files <filename>UPDATING</filename> and
+ <filename>MOVED</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
+ an entry in this file is as follows:</para>
- <programlisting>YYYYMMDD:
+ <programlisting>YYYYMMDD:
AFFECTS: users of portcategory/portname
AUTHOR: Your name <Your email address>
Special instructions</programlisting>
- <para>If you are including exact portmaster or portupgrading
- instructions, please make sure to get the shell escaping
- right.</para>
-
- <para>The <filename>/usr/ports/MOVED</filename> 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
- it was moved to can be left blank. Each section must be
- separated by the <literal>|</literal> (pipe) character, like
- so:</para>
-
- <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 end of the file to keep it in chronological order.</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>The changes can be validated with
- <command>Tools/scripts/MOVEDlint.awk</command>.</para>
- </sect1>
- </chapter>
+ <para>If you are including exact portmaster or portupgrading
+ instructions, please make sure to get the shell escaping
+ right.</para>
+
+ <para>The <filename>/usr/ports/MOVED</filename> 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
+ it was moved to can be left blank. Each section must be
+ separated by the <literal>|</literal> (pipe) character, like
+ so:</para>
+
+ <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 end of the file to keep it in chronological order.</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>The changes can be validated with
+ <command>Tools/scripts/MOVEDlint.awk</command>.</para>
+ </sect1>
+</chapter>
More information about the svn-doc-all
mailing list