diff --git a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc index b92aa1bac5..90929c9877 100644 --- a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc +++ b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc @@ -1,82 +1,87 @@ --- title: Chapter 16. Keeping Up prev: books/porters-handbook/order next: books/porters-handbook/uses --- [[keeping-up]] = Keeping Up :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 16 include::shared/mirrors.adoc[] include::shared/authors.adoc[] include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] include::shared/en/teams.adoc[] include::shared/en/urls.adoc[] toc::[] The FreeBSD Ports Collection is constantly changing. Here is some information on how to keep up. [[freshports]] == FreshPorts One of the easiest ways to learn about updates that have already been committed is by subscribing to http://www.FreshPorts.org/[FreshPorts]. Multiple ports can be monitored. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other FreeBSD committer has made. (These are often necessary to keep up with changes in the underlying ports framework-although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.) To use FreshPorts, an account is required. Those with registered email addresses at `@FreeBSD.org` will see the opt-in link on the right-hand side of the web pages. Those who already have a FreshPorts account but are not using a `@FreeBSD.org` email address can change the email to `@FreeBSD.org`, subscribe, then change it back again. FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits. [[cgit]] == The Web Interface to the Source Repository It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the https://cgit.freebsd.org/ports/tree/CHANGES[CHANGES] file. Changes that affect individual ports are now documented in the https://cgit.FreeBSD.org/ports/tree/UPDATING[UPDATING] file. However, the definitive answer to any question is undoubtedly to read the source code of https://cgit.FreeBSD.org/ports/tree/Mk/bsd.port.mk[bsd.port.mk], and associated files. [[ports-mailing-list]] == The FreeBSD Ports Mailing List As a ports maintainer, consider subscribing to {freebsd-ports}. Important changes to the way ports work will be announced there, and then committed to [.filename]#CHANGES#. If the volume of messages on this mailing list is too high, consider following {freebsd-ports-announce} which contains only announcements. [[build-cluster]] == The FreeBSD Port Building Cluster One of the least-publicized strengths of FreeBSD is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. Individual ports are built unless they are specifically marked with `IGNORE`. Ports that are marked with `BROKEN` will still be attempted, to see if the underlying problem has been resolved. (This is done by passing `TRYBROKEN` to the port's [.filename]#Makefile#.) [[distfile-survey]] == Portscout: the FreeBSD Ports Distfile Scanner The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. http://portscout.FreeBSD.org[Portscout], the FreeBSD Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. Portscout can generate HTML reports and send emails about newly available ports to those who request them. Unless not otherwise subscribed, maintainers are asked to check periodically for changes, either by hand or using the RSS feed. Portscout's first page gives the email address of the port maintainer, the number of ports the maintainer is responsible for, the number of those ports with new distfiles, and the percentage of those ports that are out-of-date. The search function allows for searching by email address for a specific maintainer, and for selecting whether only out-of-date ports are shown. Upon clicking on a maintainer's email address, a list of all of their ports is displayed, along with port category, current version number, whether or not there is a new version, when the port was last updated, and finally when it was last checked. A search function on this page allows the user to search for a specific port. Clicking on a port name in the list displays the http://freshports.org[FreshPorts] port information. Additional documentation is available in the https://github.com/freebsd/portscout[Portscout repository]. [[portsmon]] == The FreeBSD Ports Monitoring System Another handy resource is the http://portsmon.FreeBSD.org[FreeBSD Ports Monitoring System] (also known as `portsmon`). This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. In the future, this will be expanded to include the distfile survey, as well as other sources. To get started, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port] search page to find all the information about a port. This is the only resource available that maps PR entries to portnames. PR submitters do not always include the portname in their Synopsis, although we would prefer that they did. So, `portsmon` is a good place to find out whether an existing port has any PRs filed against it, any build errors, or if a new port the porter is considering creating has already been submitted. + +[NOTE] +====== +The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. +====== diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc index cff0c810d8..dc01bd897b 100644 --- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc @@ -1,195 +1,200 @@ --- title: Chapter 11. Upgrading a Port prev: books/porters-handbook/testing next: books/porters-handbook/security --- [[port-upgrading]] = Upgrading a Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 11 include::shared/mirrors.adoc[] include::shared/authors.adoc[] include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] include::shared/en/teams.adoc[] include::shared/en/urls.adoc[] toc::[] When a port is not the most recent version available from the authors, update the local working copy of [.filename]#/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 Git to keep the whole ports collection up-to-date, as described in the link:{handbook}#ports-using/[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 https://bugs.freebsd.org/search/[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 crossref:keeping-up[portsmon,FreeBSD 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 http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port]. +[NOTE] +====== +The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. +====== + 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 FreeBSD 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 [.filename]#something.orig#, save the changes to [.filename]#something# and then create the patch: [source,shell] .... % diff -u something.orig something > something.diff .... Otherwise, either use the `git 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 [.filename]#superedit# and the original is in our tree as [.filename]#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`). [NOTE] ==== 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:git[1] commands to run. ==== To simplify common operations with patch files, use `make makepatch` as described in crossref:slow-porting[slow-patch,Patching]. Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#. If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer. FreeBSD 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:{developers-handbook}#POLICIES-MAINTAINER[Developer's Handbook].) To submit the diff, use the https://bugs.freebsd.org/submit/[bug submit form] (product `Ports & Packages`, component `Individual Port(s)`). Always include the category with the port name, followed by colon, and brief descripton of the issue. Examples: `_category/portname_: _add FOO option_`; `_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:git[1] when doing a commit. Do not compress or encode the diff. Before submitting the bug, review the link:{problem-reports}#pr-writing/[ Writing the problem report] section in the Problem Reports article. It contains far more information about how to write useful problem reports. [IMPORTANT] ==== If the upgrade is motivated by security concerns or a serious fault in the currently committed port, please notify the {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. ==== [NOTE] ==== Please use man:diff[1] or `git 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 crossref:keeping-up[keeping-up,Keeping Up]. [[git-diff]] == Using Git to Make Patches When possible, please submit a man:git[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 `git diff` can be easily applied with `git apply` and will save some time to the committer. [source,shell] .... % cd ~/my_ports_wrkdir <.> % git clone https://cgit.FreeBSD.org/ports.git <.> % cd ~/my_wrkdir/dns/pdnsd .... <.> This can be anywhere, of course. Building ports is not limited to within [.filename]#/usr/ports/#. <.> https://cgit.FreeBSD.org/[cgit.FreeBSD.org] is the FreeBSD public Git server. See link:{handbook}#svn-mirrors[Subversion mirror sites] for more information. While in the port directory, make any changes that are needed. If adding, moving, or removing a file, use `git` to track these changes: [source,shell] .... % git add new_file % git mv old_name new_name % git rm deleted_file .... Make sure to check the port using the checklist in crossref:quick-porting[porting-testing,Testing the Port] and crossref:quick-porting[porting-portlint,Checking the Port with `portlint`]. [source,shell] .... % git status --short % git pull --rebase <.> .... <.> 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. The last step is to make a unified man:diff[1] of the changes: [source,shell] .... % git diff . > ../`make -VPKGNAME`.diff .... [NOTE] ==== If files have been added, moved, or removed, include the man:git[1] `add`, `mv`, and `rm` commands that were used. `git mv` must be run before the patch can be applied. `git add` or `git rm` must be run after the patch is applied. ==== Send the patch following the link:{problem-reports}#pr-writing/[problem report submission guidelines]. [[moved-and-updating-files]] == UPDATING and MOVED [[moved-and-updating-updating]] === /usr/ports/UPDATING 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: [.programlisting] .... YYYYMMDD: AFFECTS: users of portcategory/portname AUTHOR: Your name Special instructions .... [TIP] ==== When including exact portmaster, portupgrade, and/or pkg instructions, please make sure to get the shell escaping right. For example, do _not_ use: [source,shell] .... # 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: [source,shell] .... # pkg delete -g -f docbook-xml\* docbook-sk\* docbook\[2345\]\?\?-\* docbook-4\* .... ==== [NOTE] ==== 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` ==== [[moved-and-updating-moved]] === /usr/ports/MOVED 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: [.programlisting] .... 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. [NOTE] ==== Any changes must be validated with `Tools/scripts/MOVEDlint.awk`. If using a ports directory other than [.filename]#/usr/ports#, use: [source,shell] .... % cd /home/user/ports % env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk .... ====