From bc71274a347df1168efb0dc0bf77a0600fddda69 Mon Sep 17 00:00:00 2001
From: "Yann E. MORIN" <yann.morin.1998@free.fr>
Date: Sat, 4 May 2024 23:40:22 +0200
Subject: [PATCH] docs/manual: update archives version suffixes

Since tar *will* generate different archives, virtually all hashes will
change, so drop the blurb that states they usually would not.

Signed-off-by: Yann E. MORIN <yann.morin.1998@free.fr>
[Arnout: say explicitly that the has will change]
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
---
 docs/manual/migrating.adoc | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/docs/manual/migrating.adoc b/docs/manual/migrating.adoc
index 5a09c852c7..ed2be1c6c9 100644
--- a/docs/manual/migrating.adoc
+++ b/docs/manual/migrating.adoc
@@ -138,42 +138,49 @@ The download backends have been extended in various ways.
 * The git download backend now properly expands the `export-subst`
   https://git-scm.com/docs/gitattributes[git attribute] when generating
   archives.
+* A newer +tar+ version, _1.35_, is required to generate the archives.
+  For compatibility reasons, +tar+ 1.35 changes the way it stores some
+  fields (`devmajor` and `devminor`), which has an impact in the metadata
+  stored in the archives (but the content of files is not affected).
 
 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+
+* for git: +-git4+
+* for subversion: +-svn5+
+* for cargo (rust) packages: +-cargo2+
+* for go packages: +-go2+
 
 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+.
+e.g.: +libfoo-1.2.3-git4-cargo2.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 kernel and bootloaders must be updated. 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/' $(
+sed -r -i -e 's/-br2/-git4/; s/-br3/-svn5/' $(
     git grep -l -E -- '-br2|-br3' -- '*.hash'
 )
 
 # For go packages, which originally had no suffix
-sed -r -i -e 's/(\.tar\.gz)$/-go1\1/' $(
+sed -r -i -e 's/(\.tar\.gz)$/-go2\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/' $(
+sed -r -i -e 's/(\.tar\.gz)$/-cargo2\1/' $(
     git grep -l -E '\$\(eval \$\((host-)?cargo-package\)\)' -- '*.mk' \
     |sed -r -e 's/\.mk$/.hash/' \
     |sort -u
 )
 ----
+
+Note that the hash _will_ have changed, so that needs to be updated
+(manually) as well.