From owner-svn-doc-all@FreeBSD.ORG Sun Feb 9 02:36:59 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id BCC996A2; Sun, 9 Feb 2014 02:36:59 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 978141649; Sun, 9 Feb 2014 02:36:59 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s192axG0038984; Sun, 9 Feb 2014 02:36:59 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s192axtF038983; Sun, 9 Feb 2014 02:36:59 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402090236.s192axtF038983@svn.freebsd.org> From: Warren Block Date: Sun, 9 Feb 2014 02:36:59 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 09 Feb 2014 02:36:59 -0000 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$ --> - + + + Upgrading a Port + + 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 + ports/ports-current 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 + Subversion or &man.portsnap.8; to keep + your whole ports collection up-to-date, as described in the Handbook. + This will have the added benefit of tracking all the port's + dependencies. + + 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 FreeBSD + Problem Report (PR) database (also known as + GNATS). Select ports in + the dropdown, and enter the name of the port. + + 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 + &os; Ports Monitoring System + (also known as portsmon). This system + attempts to classify port PRs by portname. To search for PRs + about a particular port, use the Overview + of One Port. + + If there is no pending PR, the next step is to send an email + to the port's maintainer, as shown by + make maintainer. 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 + ports@FreeBSD.org, which is just the general + ports mailing list, so sending mail there probably will not help + in this case. + + 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. + + To create a suitable diff for a single + patch, copy the file that needs patching to + something.orig, save your changes to + something and then create your + patch: + + + &prompt.user; diff -u something.orig something > something.diff + + + Otherwise, you should either use the + svn diff method () + 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 superedit + and the original is in our tree as + superedit.bak, then save the result of + diff -ruN superedit.bak superedit). Either + unified or context diff is fine, but port committers generally + prefer unified diffs. Note the use of the -N + 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 + make clean). + + To simplify common operations with patch files, you can use + /usr/ports/Tools/scripts/patchtool.py. + Before using it, please read + /usr/ports/Tools/scripts/README.patchtool. + + 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 Developer's + Handbook.) + + The best way to send us the diff is by including it via + &man.send-pr.1; (category ports). If you are + maintaining the port, be sure to put [maintainer + update] at the beginning of your synopsis line and set + the Class of your PR to + maintainer-update. Otherwise, the + Class of your PR should be + change-request. 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. + + Before using &man.send-pr.1;, review the + Writing the problem report section in the Problem + Reports article. It contains far more information about how to + write useful problem reports. + + + 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 pkg will otherwise continue to install + the old version via pkg install for several + weeks. + + + + 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. + + + Now that you have done all that, read about + how to keep up-to-date in . + + + Using <application>Subversion</application> to Make + Patches + + When possible, please submit a &man.svn.1; diff. They + are easier to handle than diffs between + new and old 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. - Upgrading a Port - - 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 - ports/ports-current 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 - Subversion or &man.portsnap.8; - to keep your whole ports collection up-to-date, as described in - the Handbook. - This will have the added benefit of tracking all the port's - dependencies. - - 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 FreeBSD - Problem Report (PR) database (also known as - GNATS). Select ports in - the dropdown, and enter the name of the port. - - 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 - &os; Ports Monitoring System - (also known as portsmon). This system - attempts to classify port PRs by portname. To search for PRs - about a particular port, use the Overview - of One Port. - - If there is no pending PR, the next step is to send an email - to the port's maintainer, as shown by - make maintainer. 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 - ports@FreeBSD.org, which is just the general - ports mailing list, so sending mail there probably will not help - in this case. - - 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. - - To create a suitable diff for a single - patch, copy the file that needs patching to - something.orig, save your changes to - something and then create your - patch: - - - &prompt.user; diff -u something.orig something > something.diff - - - Otherwise, you should either use the - svn diff method () - 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 superedit - and the original is in our tree as - superedit.bak, then save the result of - diff -ruN superedit.bak superedit). Either - unified or context diff is fine, but port committers generally - prefer unified diffs. Note the use of the -N - 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 - make clean). - - To simplify common operations with patch files, you can use - /usr/ports/Tools/scripts/patchtool.py. - Before using it, please read - /usr/ports/Tools/scripts/README.patchtool. - - 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 Developer's - Handbook.) - - The best way to send us the diff is by including it via - &man.send-pr.1; (category ports). If you are - maintaining the port, be sure to put [maintainer - update] at the beginning of your synopsis line and set - the Class of your PR to - maintainer-update. Otherwise, the - Class of your PR should be - change-request. 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. - - Before using &man.send-pr.1;, review the - Writing the problem report section in the Problem - Reports article. It contains far more information about how to - write useful problem reports. - - - 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 pkg will otherwise continue to install - the old version via pkg install for several - weeks. - - - - 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. - - - Now that you have done all that, read about - how to keep up-to-date in . - - - Using <application>Subversion</application> to Make - Patches - - When possible, please submit a &man.svn.1; diff. They - are easier to handle than diffs between - new and old 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. - - &prompt.user; cd ~/my_wrkdir + &prompt.user; cd ~/my_wrkdir &prompt.user; svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd &prompt.user; cd ~/my_wrkdir/pdnsd - - + + - This can be anywhere you want, of course; building - ports is not limited to within - /usr/ports/. - - - - svn0.us-west.FreeBSD.org - is a public Subversion server. - Select the closest mirror and verify the mirror server - certificate from the list of Subversion - mirror sites. - - - - While in the working directory, make any changes that you - would usually make to the port. If you add or remove a file, - use svn to track these changes: + This can be anywhere you want, of course; building + ports is not limited to within + /usr/ports/. + + + + svn0.us-west.FreeBSD.org + is a public Subversion server. + Select the closest mirror and verify the mirror server + certificate from the list of Subversion + mirror sites. + + + + While in the working directory, make any changes that you + would usually make to the port. If you add or remove a file, + use svn to track these changes: - &prompt.user; svn add new_file + &prompt.user; svn add new_file &prompt.user; svn remove deleted_file - Make sure that you check the port using the checklist in - and - . + Make sure that you check the port using the checklist in + and + . - &prompt.user; svn status + &prompt.user; svn status &prompt.user; svn update - - - 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 - for a complete list. - - - - - <application>Subversion</application> Update File - Prefixes - - - - - U - The file was updated without problems. - - - - G - The file was updated without problems (you will - only see this when working against a remote - repository). - - - - M - The file had been modified, and was merged - without conflicts. - - - - C - The file had been modified, and was merged with - conflicts. - - - -
- - If C is displayed as a result of - svn update, it means something changed in - the Subversion 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. - - The last step is to make a unified &man.diff.1; - of the changes: - - &prompt.user; svn diff > ../`basename ${PWD}`.diff - - - Any files that have been removed should be explicitly - mentioned in the PR, because file removal may not be obvious - to the committer. - - - Send your patch following the guidelines in - . - - - - The Files <filename>UPDATING</filename> and - <filename>MOVED</filename> - - If upgrading the port requires special steps like - changing configuration files or running a specific program, - you should document this in the file - /usr/ports/UPDATING. The format of - an entry in this file is as follows: + + + 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 + for a complete list. + + + + + <application>Subversion</application> Update File + Prefixes + + + + + U + The file was updated without problems. + + + + G + The file was updated without problems (you will + only see this when working against a remote + repository). + + + + M + The file had been modified, and was merged + without conflicts. + + + + C + The file had been modified, and was merged with + conflicts. + + + +
+ + If C is displayed as a result of + svn update, it means something changed in + the Subversion 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. + + The last step is to make a unified &man.diff.1; + of the changes: + + &prompt.user; svn diff > ../`basename ${PWD}`.diff + + + Any files that have been removed should be explicitly + mentioned in the PR, because file removal may not be obvious + to the committer. + + + Send your patch following the guidelines in + . + + + + The Files <filename>UPDATING</filename> and + <filename>MOVED</filename> + + If upgrading the port requires special steps like + changing configuration files or running a specific program, + you should document this in the file + /usr/ports/UPDATING. The format of + an entry in this file is as follows: - YYYYMMDD: + YYYYMMDD: AFFECTS: users of portcategory/portname AUTHOR: Your name <Your email address> Special instructions - If you are including exact portmaster or portupgrading - instructions, please make sure to get the shell escaping - right. - - The /usr/ports/MOVED 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 | (pipe) character, like - so: - - old name|new name (blank for deleted)|date of move|reason - - The date should be entered in the form - YYYY-MM-DD. New entries should be added to - the end of the file to keep it in chronological order. - - If a port was removed but has since been restored, - delete the line in this file that states that it was - removed. - - The changes can be validated with - Tools/scripts/MOVEDlint.awk. - - + If you are including exact portmaster or portupgrading + instructions, please make sure to get the shell escaping + right. + + The /usr/ports/MOVED 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 | (pipe) character, like + so: + + old name|new name (blank for deleted)|date of move|reason + + The date should be entered in the form + YYYY-MM-DD. New entries should be added to + the end of the file to keep it in chronological order. + + If a port was removed but has since been restored, + delete the line in this file that states that it was + removed. + + The changes can be validated with + Tools/scripts/MOVEDlint.awk. + +