Index: head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml (revision 52123) +++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml (revision 52124) @@ -1,390 +1,383 @@ Upgrading a Port When a port is not the most recent version available from the authors, update the local working copy of /usr/ports. The port might have already been updated to the new version. When working with more than a few ports, it will probably be easier to use Subversion to keep the 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, there are two options. There is a searchable interface to the FreeBSD Problem Report (PR) or bug database. Select Ports & Packages in the Product multiple select menu, and enter the name of the port in the Summary field. However, sometimes people forget to put the name of the port into the Summary field in an unambiguous fashion. In that case, try searching in the Comment field in the Detailled Bug Information section, or 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), and there is no need 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 help out &os; by preparing the update! 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 the changes to something and then create the patch: &prompt.user; diff -u something.orig something > something.diff Otherwise, 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 (for example, if the 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 to first clean out the work directories with make clean). If some files have been added, copied, moved, or removed, add this information to the problem report so that the committer picking up the patch will know what &man.svn.1; commands to run. To simplify common operations with patch files, use make makepatch as described in . Other tools exists, like /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, 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.) To submit the diff, use the bug submit form (product Ports & Packages, component Individual Port(s)). If the submitter is also maintaining the port, be sure to put [MAINTAINER] at the beginning of the Summary line. Always include the category with the port name, followed by colon, and brief descripton of the issue. For example: category/portname: add FOO option, or if maintaining the port, [MAINTAINER] category/portname: Update to X.Y. 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. Do not compress or encode the diff. Before submitting the bug, 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. Please use &man.diff.1; or svn diff to create updates to existing ports. Other formats include the whole file and make it impossible to see just what has changed. When diffs are not included, the entire update might be ignored. Now that all of that is done, 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 the work on it began, or if the committer asks for something to be fixed. Also, a patch generated with svn diff can be easily applied with svn patch and will save some time to the committer. &prompt.user; cd ~/my_wrkdir &prompt.user; svn co https://svn.FreeBSD.org/ports/head/dns/pdnsd &prompt.user; cd ~/my_wrkdir/pdnsd This can be anywhere, of course. Building ports is not limited to within /usr/ports/. svn.FreeBSD.org is the &os; public Subversion server. See Subversion mirror sites for more information. While in the port directory, make any changes that are needed. If adding, copying, moving, or removing a file, use svn to track these changes: &prompt.user; svn add new_file &prompt.user; svn copy some_file file_copy &prompt.user; svn move old_name new_name &prompt.user; svn remove deleted_file Make sure to check the port using the checklist in and . &prompt.user; svn status &prompt.user; svn update 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 for a complete list. <application>Subversion</application> Update File Prefixes U The file was updated without problems. G The file was updated without problems (only 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 the structure of a port, 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 > ../`make -VPKGNAME`.diff If files have been added, copied, moved, or removed, include the &man.svn.1; add, copy, move, and remove commands that were used. svn move or svn copy must be run before the patch can be applied. svn add or svn remove must be run after the patch is applied. Send the patch following the problem report submission guidelines. - - - The patch can be automatically generated and the PR - pre-filled with the contact information by using - port submit. See for more details. - <filename>UPDATING</filename> and <filename>MOVED</filename> <filename>/usr/ports/UPDATING</filename> If upgrading the port requires special steps like changing configuration files or running a specific program, it must be documented in this file. The format of an entry in this file is: YYYYMMDD: AFFECTS: users of portcategory/portname AUTHOR: Your name <Your email address> Special instructions When including exact portmaster, portupgrade, and/or pkg instructions, please make sure to get the shell escaping right. For example, do not use: &prompt.root; pkg delete -g -f docbook-xml* docbook-sk* docbook[2345]??-* docbook-4* As shown, the command will only work with bourne shells. Instead, use the form shown below, which will work with both bourne shell and c-shell: &prompt.root; pkg delete -g -f docbook-xml\* docbook-sk\* docbook\[2345\]\?\?-\* docbook-4\* 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 BIND 9 versions the AFFECTS content must be users of dns/bind9*, it must not be users of BIND 9 <filename>/usr/ports/MOVED</filename> 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, when, and why. If the port was removed, the section detailing where it was moved 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 must be entered in the form YYYY-MM-DD. New entries are added to the end of the list to keep it in chronological order, with the oldest entry at the top of the list. If a port was removed but has since been restored, delete the line in this file that states that it was removed. If a port was renamed and then renamed back to its original name, add a new one with the intermediate name to the old name, and remove the old entry as to not create a loop. Any changes must be validated with Tools/scripts/MOVEDlint.awk. If using a ports directory other than /usr/ports, use: &prompt.user; cd /home/user/ports &prompt.user; env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk