* [gentoo-commits] proj/devmanual:master commit in: general-concepts/mirrors/, general-concepts/manifest/
@ 2023-10-29 20:22 Sam James
0 siblings, 0 replies; only message in thread
From: Sam James @ 2023-10-29 20:22 UTC (permalink / raw
To: gentoo-commits
commit: dbc3fda4b0ca7be794e0aeea1ca3c775313cf86f
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Thu Oct 26 23:35:47 2023 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sun Oct 29 20:22:51 2023 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=dbc3fda4
general-concepts: discuss concerns with regenerating existing distfile entries
In a discussion with Eli Schwartz, I realised the devmanual doesn't currently
explicitly state best practice.
In general-concepts/mirrors, link to the new Manifest regeneration section
and shift some text around into that new section too (and adjust the text slightly
while at it).
Signed-off-by: Sam James <sam <AT> gentoo.org>
Closes: https://github.com/gentoo/devmanual/pull/318
Signed-off-by: Sam James <sam <AT> gentoo.org>
general-concepts/manifest/text.xml | 36 ++++++++++++++++++++++++++++++++++++
general-concepts/mirrors/text.xml | 9 ++-------
2 files changed, 38 insertions(+), 7 deletions(-)
diff --git a/general-concepts/manifest/text.xml b/general-concepts/manifest/text.xml
index 19ea5c3..bee1651 100644
--- a/general-concepts/manifest/text.xml
+++ b/general-concepts/manifest/text.xml
@@ -39,6 +39,42 @@ action from developers.
</p>
</body>
</subsection>
+
+<subsection>
+<title>Updating <c>Manifest</c> files</title>
+<body>
+
+<p>
+Updating existing entries within a manifest must be done with care. Upstream
+changing the tarball in-place without a new filename could be an innocent
+respin of the tarball, or it could indicate either the previous or the new
+tarball is malicious.
+</p>
+
+<p>
+Developers should diff the old and new versions of the distfile, comparing
+the two, and note the differences in the commit message updating the
+<c>Manifest</c> to indicate both what happened (if any context is known) and
+also what differences between the two distfiles have been ascertained.
+</p>
+
+<p>
+Please note that if upstream made any changes affecting the built
+package or it had substantial differences, you need to also bump the ebuild's
+revision. Finally, remember to remove the ebuilds that are associated with the
+old distfile, or regenerate their checksums in <c>Manifest</c>, if there
+are any. This is necessary because these ebuilds will cause checksum
+mismatch errors as the checksum recorded in the manifest file no
+longer matches the computed checksum of the fetched distfile.
+</p>
+
+<p>
+Special care is also required with regard to
+<uri link="::general-concepts/mirrors/#Replacing Automatically Mirrored Files">
+mirrors</uri>.
+</p>
+</body>
+</subsection>
</section>
</chapter>
</guide>
diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml
index 6b4993e..f1ce1bb 100644
--- a/general-concepts/mirrors/text.xml
+++ b/general-concepts/mirrors/text.xml
@@ -68,13 +68,8 @@ fetch and start distributing the new version.
</p>
<p>
-Please note that if upstream made any changes affecting the built
-package, you need to also bump the ebuild's revision. Finally,
-remember to remove the ebuilds that are associated with the old
-distfile, or regenerate their checksums in <c>Manifest</c>, if there
-are any. This is necessary because these ebuilds will cause checksum
-mismatch errors as the checksum recorded in the Manifest file no
-longer matches the computed checksum of the fetched distfile.
+Updating an existing distfile is generally cause for concern and must be done
+with care, see <uri link="::general-concepts/manifest/#Updating Manifests"/>.
</p>
<p>
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2023-10-29 20:23 UTC | newest]
Thread overview: (only message) (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-10-29 20:22 [gentoo-commits] proj/devmanual:master commit in: general-concepts/mirrors/, general-concepts/manifest/ Sam James
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox