diff options
Diffstat (limited to 'documentation/content/en/books/porters-handbook/upgrading/_index.adoc')
| -rw-r--r-- | documentation/content/en/books/porters-handbook/upgrading/_index.adoc | 94 |
1 files changed, 66 insertions, 28 deletions
diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc index b93d0dac18..6978f0577c 100644 --- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc @@ -4,6 +4,9 @@ prev: books/porters-handbook/testing next: books/porters-handbook/security description: Upgrading a FreeBSD Port tags: ["upgrading", "port", "git"] +showBookMenu: true +weight: 11 +path: "/books/porters-handbook/upgrading/" --- [[port-upgrading]] @@ -14,28 +17,41 @@ tags: ["upgrading", "port", "git"] :icons: font :sectnums: :sectnumlevels: 6 +:sectnumoffset: 11 +:partnums: :source-highlighter: rouge :experimental: -:skip-front-matter: -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: -:sectnumoffset: 11 +:images-path: books/porters-handbook/ -include::shared/mirrors.adoc[] +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] include::shared/authors.adoc[] +include::shared/mirrors.adoc[] include::shared/releases.adoc[] -include::shared/en/mailing-lists.adoc[] -include::shared/en/teams.adoc[] -include::shared/en/urls.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] +ifndef::env-beastie[] toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] 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]. +as described in extref:{handbook}ports[Using the Ports Collection, ports-using]. 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. @@ -43,16 +59,6 @@ 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. @@ -83,15 +89,15 @@ Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchto 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].) +(For a detailed description of the responsibilities of maintainers, refer to the section in the extref:{developers-handbook}[Developer's Handbook, POLICIES-MAINTAINER].) 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. +Always include the category with the port name, followed by colon, and brief description 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. +Before submitting the bug, review the extref:{problem-reports}[Writing the problem report, pr-writing] section in the Problem Reports article. It contains far more information about how to write useful problem reports. [IMPORTANT] @@ -113,11 +119,13 @@ Now that all of that is done, read about how to keep up-to-date in crossref:keep [[git-diff]] == Using Git to Make Patches -When possible, please submit a man:git[1] diff. +When possible, please submit a man:git[1] patch or 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. +Also, a patch generated with man:git-format-patch[1] or man:git-diff[1] can be easily applied with man:git-am[1] or man:git-apply[1] and will save some time for the committer. +Finally, the git patch generated by man:git-format-patch[1] includes your author information and commit messages. +These will be recorded in the log of the repository and this is the recommended way to submit your changes. [source,shell] .... @@ -127,7 +135,7 @@ Also, a patch generated with `git diff` can be easily applied with `git apply` a <.> This can be anywhere, of course. Building ports is not limited to within [.filename]#/usr/ports/#. -<.> https://git.FreeBSD.org/[git.FreeBSD.org] is the FreeBSD public Git server. See link:{handbook}mirrors/#git-url-table[FreeBSD Git Repository URL Table] for more information. +<.> https://git.FreeBSD.org/[git.FreeBSD.org] is the FreeBSD public Git server. See extref:{handbook}mirrors[FreeBSD Git Repository URL Table, git-url-table] 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: @@ -141,6 +149,8 @@ If adding, moving, or removing a file, use `git` to track these changes: 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`]. +Also, update the checksum reference in distinfo with `make makesum`. + Before making the patch, fetch the latest repository and rebase the changes on top of it. Watch and follow the output carefully. If any of the files failed to rebase, it means that the upstream files changed while you were editing the same file, and the conflicts need to be resolved manually. @@ -159,12 +169,40 @@ Check the changes staged for the patch: % git diff --staged .... -The last step is to make a unified man:diff[1] of the changes: +The last step is to make an unified diff or patch of the changes: + +To generate a patch with man:git-format-patch[1]: +[source,shell] +.... +% git checkout -b my_branch +% git commit +% git format-patch main +.... + +This will generate a patch named like `0001-foo.patch`. +This is the preferred way as it would include author identity, +and it is also easier when you are making a series of changes that +are not meant to be squashed together. +Alternatively, to generate an unified diff with man:git-diff[1]: [source,shell] .... % git diff --staged > ../`make -VPKGNAME`.diff .... +This will generate a diff named like `foo-1.2.3.diff`. +Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message. + +After patch has been created, you can switch to the main branch for starting other developments. +[source,shell] +.... +% git checkout main +.... + +Once the patch is accepted and merged, you can delete the local development branch if you want: +[source,shell] +.... +% git branch -D my_branch +.... [NOTE] ==== @@ -173,7 +211,7 @@ If files have been added, moved, or removed, include the man:git[1] `add`, `mv`, `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]. +Send the patch following the extref:{problem-reports}[problem report submission guidelines, pr-writing]. [[moved-and-updating-files]] == UPDATING and MOVED |