Page MenuHomeFreeBSD
Files F170833340

D57361.diff
No OneTemporary
Actions

D57361.diff
View Options

diff --git a/documentation/content/en/articles/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc
--- a/documentation/content/en/articles/freebsd-releng/_index.adoc
+++ b/documentation/content/en/articles/freebsd-releng/_index.adoc
@@ -661,6 +661,114 @@
% git tag {tagReleasex}
....
+[[releng-troubleshooting]]
+=== Troubleshooting
+
+==== How to fix a release ports tag when an external file breaks a required port
+
+[descrete]
+===== Problem:
+
+* The release uses a fixed ports tag (e.g., release/15.1.0).
+* A port depends on an external file (patch, distfile) that changed after the tag was created (upstream replaced it, GitHub changed a short hash length, etc.).
+* The release build fails because of a checksum mismatch.
+* A fix for the port already exists in the main ports tree (or in a quarterly branch) but is not in the release tag.
+
+[descrete]
+===== Solution:
+
+Create a new tag (e.g., release/15.1.0a) based on the old tag plus a single cherry-pick of the fix.
+Do not push a public branch unless you need it for later fixes.
+The commit must contain an "Approved by:" line.
+
+Step-by-step actions (example: release/15.1.0 -> release/15.1.0a):
+
+1. Clone the ports repository if you do not have it yet (as recommended in the extref:{committers-guide}[Committer's Guide, git-mini-daily-use]):
++
+[source,shell,subs="attributes"]
+....
+% git clone -o freebsd --config remote.freebsd.fetch='+refs/notes/*:refs/notes/*' https://git.freebsd.org/ports.git freebsd-ports
+% cd freebsd-ports
+....
+
+2. Create a local temporary branch from the old tag:
++
+[source,shell,subs="attributes"]
+....
+% git checkout -b temp-release release/15.1.0
+....
+
+3. Cherry-pick the fix commit from the main tree (use `-x` to add a "cherry picked from" line to the commit message):
++
+[source,shell,subs="attributes"]
+....
+% git cherry-pick -x 4b4b105e82c91455a47ca32c79525a88a60b8616
+....
+
+4. Add an "Approved by:" line to the commit message if it does not have one. Amend the commit:
++
+[source,shell,subs="attributes"]
+....
+% git commit --amend
+....
++
+Add somewhere in the message (usually at the end):
++
+[.programlisting,subs="attributes"]
+....
+Approved by: portmgr (implicit, re blanket)
+....
++
+Important: use exactly `Approved by:` (space, not a hyphen).
+The line must be inside the commit, not only in the tag message.
+
+5. Create an annotated and GPG-signed tag:
++
+[source,shell,subs="attributes"]
+....
+% git tag -s release/15.1.0a -m "Release 15.1.0a with cherry-picked fix"
+....
+
+6. Verify the tag points to the correct commit:
++
+[source,shell,subs="attributes"]
+....
+% git show release/15.1.0a
+....
+
+7. Push only the tag to the official repository (do not push the temporary branch):
++
+[source,shell,subs="attributes"]
+....
+% git push freebsd release/15.1.0a
+....
++
+If the approval hook still rejects, ensure the `Approved by:` line is present in the commit (not just the tag).
+You may also need `--push-option=confirm-author` in some environments.
+
+8. Leave the temporary branch (checkout any other branch), then delete it:
++
+[source,shell,subs="attributes"]
+....
+% git checkout main
+% git branch -D temp-release
+....
+
+9. Restart the release builds using the new tag (release/15.1.0a).
+This may require adjusting the build orchestration code (e.g., the script or system that invokes the release build) to use the new tag.
+
+[descrete]
+===== Notes:
+
+* If the hook rejects the tag, double-check that the commit message contains `Approved by:` on its own line.
+The format that worked for release/15.1.0 is "Approved by: portmgr (implicit, re blanket)".
+
+* Do not push a releng/15.1 branch unless you expect to add more fixes later.
+For a single fix a tag is enough.
+
+* To prevent such problems in the future, ports should not use dynamic GitHub patches directly in `PATCHFILES`.
+Either use `?full_index=1` in the URL or store the patch statically in the [.filename]#files/# directory.
+
[[releng-mirrors]]
== Publishing FreeBSD Installation Media to Project Mirrors

File Metadata

Mime Type
text/plain
Expires
Mon, Sep 7, 10:19 PM (7 h, 6 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
38490064
Default Alt Text
D57361.diff (3 KB)

Event Timeline