Date: Sun, 9 Feb 2014 02:36:59 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43842 - head/en_US.ISO8859-1/books/porters-handbook/upgrading Message-ID: <201402090236.s192axtF038983@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402090236.s192axtF038983>