Path: blob/main/documentation/content/en/books/porters-handbook/upgrading/_index.po
18099 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-11-08 16:17+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: YAML Front Matter: description #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:1 #, no-wrap msgid "Upgrading a FreeBSD Port" msgstr "" #. type: YAML Front Matter: title #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:1 #, no-wrap msgid "Chapter 11. Upgrading a Port" msgstr "" #. type: Title = #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:14 #, no-wrap msgid "Upgrading a Port" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:53 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:57 msgid "" "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 extref:" "{handbook}ports[Using the Ports Collection, ports-using]. This will have " "the added benefit of tracking all the port's dependencies." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:62 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:66 msgid "" "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 `[email protected]`, which is just the general ports " "mailing list, so sending mail there probably will not help in this case." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:68 msgid "" "If the maintainer requests 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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:70 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:74 #, no-wrap msgid "% diff -u something.orig something > something.diff\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:81 msgid "" "Otherwise, either use the `git diff` method (crossref:upgrading[git-diff, " "Using Git to Make Patches]) 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`)." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:85 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:90 msgid "" "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#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:94 msgid "" "If the port is unmaintained, and it is actively being used, 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 extref:{developers-handbook}policies[Developer's " "Handbook, policies-maintainer].)" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:100 msgid "" "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 " "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:103 msgid "" "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." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:109 msgid "" "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." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:116 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:119 msgid "" "Now that all of that is done, read about how to keep up-to-date in " "crossref:keeping-up[keeping-up,Keeping Up]." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:121 #, no-wrap msgid "Using Git to Make Patches" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:130 msgid "" "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 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 the author information and " "commit messages. These will be recorded in the log of the repository and " "this is the recommended way to submit the changes." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:135 #, no-wrap msgid "" "% git clone https://git.FreeBSD.org/ports.git ~/my_wrkdir <.> <.>\n" "% cd ~/my_wrkdir\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:138 msgid "" "This can be anywhere, of course. Building ports is not limited to within " "[.filename]#/usr/ports/#." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:140 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:143 msgid "" "While in the port directory, make any changes that are needed. If adding, " "moving, or removing a file, use `git` to track these changes:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:149 #, no-wrap msgid "" "% git add new_file\n" "% git mv old_name new_name\n" "% git rm deleted_file\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:152 msgid "" "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`]." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:154 msgid "Also, update the checksum reference in distinfo with `make makesum`." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:158 msgid "" "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 local " "changes happened in the same file, and the conflicts need to be resolved " "manually." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:163 #, no-wrap msgid "" "% git fetch origin main\n" "% git rebase origin/main\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:166 msgid "Check the changes staged for the patch:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:171 #, no-wrap msgid "" "% git status\n" "% git diff --staged\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:174 msgid "The last step is to make an unified diff or patch of the changes:" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:176 msgid "To generate a patch with man:git-format-patch[1]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:181 #, no-wrap msgid "" "% git checkout -b my_branch\n" "% git commit\n" "% git format-patch main\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:187 msgid "" "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 making a series of changes that are not meant to be squashed together." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:189 msgid "Alternatively, to generate an unified diff with man:git-diff[1]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:192 #, no-wrap msgid "% git diff --staged > ../`make -VPKGNAME`.diff\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:195 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:197 msgid "" "After patch has been created, switch to the main branch for starting other " "developments." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:200 #, no-wrap msgid "% git checkout main\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:203 msgid "" "Once the patch is accepted and merged, delete the local development branch " "if desired:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:206 #, no-wrap msgid "% git branch -D my_branch\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:213 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:216 msgid "" "Send the patch following the extref:{problem-reports}[problem report " "submission guidelines, pr-writing]." msgstr "" #. type: Title == #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:218 #, no-wrap msgid "UPDATING and MOVED" msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:221 #, no-wrap msgid "/usr/ports/UPDATING" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:225 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:231 #, no-wrap msgid "" "YYYYMMDD:\n" " AFFECTS: users of portcategory/portname\n" " AUTHOR: the name <the email address>\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:233 #, no-wrap msgid " Special instructions\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:240 msgid "" "When including exact portmaster, portupgrade, and/or pkg instructions, " "please make sure to get the shell escaping right. For example, do _not_ use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:244 #, no-wrap msgid "# pkg delete -g -f docbook-xml* docbook-sk* docbook[2345]??-* docbook-4*\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:248 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:252 #, no-wrap msgid "# pkg delete -g -f docbook-xml\\* docbook-sk\\* docbook\\[2345\\]\\?\\?-\\* docbook-4\\*\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:260 msgid "" "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`" msgstr "" #. type: Title === #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:263 #, no-wrap msgid "/usr/ports/MOVED" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:269 msgid "" "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:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:273 #, no-wrap msgid "old name|new name (blank for deleted)|date of move|reason\n" msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:277 msgid "" "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." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:279 msgid "" "If a port was removed but has since been restored, delete the line in this " "file that states that it was removed." msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:281 msgid "" "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." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:285 msgid "Any changes must be validated with `Tools/scripts/MOVEDlint.awk`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:287 msgid "If using a ports directory other than [.filename]#/usr/ports#, use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/porters-handbook/upgrading/_index.adoc:292 #, no-wrap msgid "" "% cd /home/user/ports\n" "% env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk\n" msgstr ""