commit: ec810986a9150209cb45f0bbeefb4b644f1b82b8
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Oct 6 08:28:15 2019 +0000
Commit: Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Wed Oct 16 19:54:33 2019 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ec810986
ebuild-writing/variables: Expand on when not to use tpm
Reintegrate the warning not to use thirdpartymirrors into main text
flow. Expand on valid use cases for using it, and word the case against
using it more strongly.
Acked-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>
ebuild-writing/variables/text.xml | 31 ++++++++++++++++++++++---------
1 file changed, 22 insertions(+), 9 deletions(-)
diff --git a/ebuild-writing/variables/text.xml
b/ebuild-writing/variables/text.xml
index 73ad8cf..e65d811 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -435,15 +435,28 @@ that can afterwards be referenced through a
<c>mirror://</c> URL:
SRC_URI="mirror://example/${PN}/${P}.tar.gz"
</codesample>
-<warning>
-If the sources for a package are neither mirror-restricted nor
-fetch-restricted, then they will be <uri
-link="::general-concepts/mirrors">mirrored onto Gentoo infrastructure</uri>
-automatically; in that case, there is little benefit to using this feature.
-There is a maintenance burden associated with using a third-party mirror list:
-it must be updated when new mirrors are born and when old mirrors die. Please
-consider that when deciding whether or not to use this feature.
-</warning>
+<p>
+There are two valid cases for using <c>thirdpartymirrors</c>:
+</p>
+
+<ol>
+ <li>
+ providing multiple download locations for mirror- or fetch-restricted
+ packages,
+ </li>
+
+ <li>
+ dealing with upstreams that distribute their distfiles via a network
+ of mirrors without a primary download location or a bouncer service.
+ </li>
+</ol>
+
+<p>
+In any other case, the primary location must be used instead. The distfiles
+will be <uri link="::general-concepts/mirrors">mirrored onto Gentoo
+infrastructure</uri>; in that case, the benefit to using third-party mirror
+list does not outweigh the burden of maintaining it.
+</p>
</body>
</subsection>
