docs/manual: document new archive version suffix

Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
[Arnout: add sed scripts for hash file update]
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>

docs/manual/migrating.adoc

@@ -127,9 +127,53 @@ that such patches will most probably not be accepted.
 [[migrating-git-attributes]]
 === Migrating to 2024.05
 
-The git download backend now properly expands the `export-subst`
-https://git-scm.com/docs/gitattributes[git attribute] when generating
-archives. Because of this, the archive version suffix has been updated,
-to +-br2+, so the hash files must be updated accordingly. Since
-`export-subst` is usually not used, the hash itself usually doesn't change,
-so the update can be done with `sed -r -i e 's/-br1/-br2/'`.
+The download backends have been extended in various ways.
+
+* All locally generated tarballs are even more reproducible. Before
+  2024.05, it was possible that the access mode of files in the archives
+  were not consistent when the download directory has specific ACLs (e.g.
+  with the +default+ ACL set). This impacts the archives generated for
+  git and subversion repositories, as well as those for vendored cargo
+  and go packages.
+* The git download backend now properly expands the `export-subst`
+  https://git-scm.com/docs/gitattributes[git attribute] when generating
+  archives.
+
+To accomodate those changes, the archive suffix has been updated or
+added:
+
+* for git: +-git3+
+* for subversion: +-svn4+
+* for cargo (rust) packages: +-cargo1+
+* for go packages: +-go1+
+
+Note that, if two such prefixes would apply to a generated archive, like
+for a cargo package downloaded from git, both suffixes need to be added,
+first the one for the download mechanism, then the one for the vendoring,
+e.g.: +libfoo-1.2.3-git3-cargo1.tar.gz+.
+
+Because of this, the hash file of any custom packages or custom versions
+for kernel and bootloaders must be updated. In most cases, the hash itself
+will not have changed. In that case, the following sed scripts can automate
+the rename in the hash file (assuming such files are kept under git).
+
+----
+# For git and svn packages, which originally had -br2 resp. -br3 suffix
+sed -r -i -e 's/-br2/-git3/; s/-br3/-svn4/' $(
+    git grep -l -E -- '-br2|-br3' -- '*.hash'
+)
+
+# For go packages, which originally had no suffix
+sed -r -i -e 's/(\.tar\.gz)$/-go1\1/' $(
+    git grep -l -E '\$\(eval \$\((host-)?golang-package\)\)' -- '*.mk' \
+    |sed -r -e 's/\.mk$/.hash/' \
+    |sort -u
+)
+
+# For cargo packages, which originally had no suffix
+sed -r -i -e 's/(\.tar\.gz)$/-cargo1\1/' $(
+    git grep -l -E '\$\(eval \$\((host-)?cargo-package\)\)' -- '*.mk' \
+    |sed -r -e 's/\.mk$/.hash/' \
+    |sort -u
+)
+----