Index: head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml @@ -11,29 +11,32 @@ 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 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, you have two options. There is a searchable interface + To do this, there are 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. + xlink:href="https://bugs.freebsd.org/search/">FreeBSD + Problem Report (PR) or bug database. + Select Ports Tree in + the Product dropdown, and enter the name of the port in the + Summary field. 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 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 @@ -46,32 +49,32 @@ 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 + 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 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. 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 + something.orig, save the changes to + something and then create the patch: - &prompt.user; diff -u something.orig something > something.diff + &prompt.user; diff -u something.orig something > something.diff - Otherwise, you should either use the + 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 (e.g., if your + 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 @@ -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 make clean). - To simplify common operations with patch files, you can use + 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 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.) - The best way to send us the diff is by including it via - &man.send-pr.1; (category ports). If you are + To submit the diff, use the bug submit + form (category Ports Tree). If the + submitter is also 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 + update] at the beginning of the + Summary 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. + specified to &man.svn.1; when doing a commit. Do not compress or + encode the diff. - Before using &man.send-pr.1;, review the Before submitting the bug, review the Writing the problem report 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. - Now that you have done all that, read about + Now that all of that is done, read about how to keep up-to-date in . @@ -145,8 +150,8 @@ 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 + 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 @@ -159,7 +164,7 @@ - This can be anywhere you want, of course; building + This can be anywhere, of course. Building ports is not limited to within /usr/ports/. @@ -175,15 +180,15 @@ - While in the working directory, make any changes that you - would usually make to the port. If you add, move or remove a + While in the port directory, make any changes that are + needed. If adding, moving, or removing a file, use svn to track these changes: - &prompt.user; svn add new_file -&prompt.user; svn move old_name new_name -&prompt.user; svn remove deleted_file + &prompt.user; svn add new_file +&prompt.user; svn move old_name new_name +&prompt.user; svn remove deleted_file - Make sure that you check the port using the checklist in + Make sure to check the port using the checklist in and . @@ -192,8 +197,8 @@ - This will try to merge the differences between your - patch and current repository version; watch the output + 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. @@ -213,8 +218,8 @@ G - The file was updated without problems (you will - only see this when working against a remote + The file was updated without problems (only when + working against a remote repository). @@ -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. The last step is to make a unified &man.diff.1; of the changes: - &prompt.user; svn diff > ../`basename ${PWD}`.diff + &prompt.user; svn diff > ../`make -VPKGNAME`.diff - Any files that have been removed should be explicitly + Any files that have been removed have to be explicitly mentioned in the PR, because file removal may not be obvious to the committer. - Send your patch following the guidelines in + Send the patch following the guidelines in . - You can have patch automatically generated and the PR - pre-filled with your contact information by using - the Port Tools port - submit command. See The patch can be automatically generated and the PR + pre-filled with the contact information by using + port submit. See for more details. - The Files <filename>UPDATING</filename> and + <title><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, - you should document this in the file - /usr/ports/UPDATING. The format of + it must be documented in this file. The format of an entry in this file is as follows: YYYYMMDD: @@ -281,22 +287,42 @@ Special instructions - If you are including exact portmaster or portupgrading - instructions, please make sure to get the shell escaping - right. + + 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 should be - users of dns/bind9*, it should + versions the AFFECTS content must be + users of dns/bind9*, it must not be users of BIND 9 - The /usr/ports/MOVED file is used to + + + + <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 to, when, and why. If the port was removed, the section detailing where @@ -306,22 +332,32 @@ 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 top of the file to keep it in reverse chronological order - (the latest entries first). + The date must be entered in the form + YYYY-MM-DD. New entries are added to + the top of the file to keep it in reverse chronological order, + with the last entry first. 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, 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. - The changes can be validated with - Tools/scripts/MOVEDlint.awk. + + 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 + + +