aboutsummaryrefslogtreecommitdiff
path: root/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
blob: 14ddf24af67ddc340c7a104fc1aa5697d797116d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
---
title: Chapter 11. Upgrading a Port
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/"
---

[[port-upgrading]]
= Upgrading a Port
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 11
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/porters-handbook/

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/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 extref:{handbook}[Handbook, 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.
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.

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 (<<git-diff>>) 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 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.
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 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]
====
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] 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 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]
....
% git clone https://git.FreeBSD.org/ports.git ~/my_wrkdir <.> <.>
% cd ~/my_wrkdir
....

<.> 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 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:

[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`].

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.

[source,shell]
....
% git fetch origin main
% git rebase origin/main
....

Check the changes staged for the patch:

[source,shell]
....
% git status
% git diff --staged
....

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]
====
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 extref:{problem-reports}[problem report submission guidelines, pr-writing].

[[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 <Your email address>

  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
....
====