<pre style='margin:0'>
Joshua Root (jmroot) pushed a commit to branch master
in repository macports-guide.

</pre>
<p><a href="https://github.com/macports/macports-guide/commit/21eb6de30535fdc1803fd312680a5fa31b22c225">https://github.com/macports/macports-guide/commit/21eb6de30535fdc1803fd312680a5fa31b22c225</a></p>
<pre style="white-space: pre; background: #F8F8F8">The following commit(s) were added to refs/heads/master by this push:
<span style='display:block; white-space:pre;color:#404040;'>     new 21eb6de  guide: update github.tarball_from docs
</span>21eb6de is described below

<span style='display:block; white-space:pre;color:#808000;'>commit 21eb6de30535fdc1803fd312680a5fa31b22c225
</span>Author: Joshua Root <jmr@macports.org>
AuthorDate: Thu Jan 30 10:16:34 2025 +1100

<span style='display:block; white-space:pre;color:#404040;'>    guide: update github.tarball_from docs
</span>---
 guide/xml/portgroup-github.xml | 82 +++++++++++++++++++++++-------------------
 1 file changed, 45 insertions(+), 37 deletions(-)

<span style='display:block; white-space:pre;color:#808080;'>diff --git a/guide/xml/portgroup-github.xml b/guide/xml/portgroup-github.xml
</span><span style='display:block; white-space:pre;color:#808080;'>index 5f0cca8..6974c70 100644
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>--- a/guide/xml/portgroup-github.xml
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>+++ b/guide/xml/portgroup-github.xml
</span><span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -91,27 +91,55 @@ github.setup        author project version v</programlisting>
</span>         </listitem>
         <listitem>
           <para>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-            Distfile from Github auto-generated archive downloads
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+            Distfile from Github legacy auto-generated tarball downloads
</span>           </para>
         </listitem>
       </itemizedlist>
     </para>
 
     <para>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-      The default behaviour of the portgroup is using GitHub automatically
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      generated distfile from a <code>git</code> commit or tag.  However, the
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      best practice should be using a GitHub release.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      The default behaviour of the portgroup is to use GitHub releases.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      However, not all projects offer releases, so it may be necessary to
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      instead use an automatically generated distfile from a
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      <code>git</code> commit or tag.
</span>     </para>
   </section>
 
<span style='display:block; white-space:pre;background:#ffe0e0;'>-  <section xml:id="reference.portgroup.github.distfile">
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+  <section xml:id="reference.portgroup.github.releases">
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+    <title>Distfile from a GitHub release</title>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+    <para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      The <code>github</code> portgroup allows maintainers to easily configure
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      the distfiles when the project uses GitHub releases.  A release is the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      best distfile candidate, and project maintainers should be encouraged to
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      use them.  To enable this feature, the following keyword should be used:
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      <programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+github.tarball_from releases</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      By default, the <code>github</code> portgroup sets <code>distname</code>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      to:
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      <programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+distname            ${github.project}-${github.version}</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      However, GitHub does not enforce any rule for release distfiles, so port
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      maintainers may need to override the <code>distname</code> as they would
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      do for other ports.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+    </para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+  </section>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+  <section xml:id="reference.portgroup.github.archive">
</span>     <title>Distfile from tag or commit</title>
 
     <para>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-      The default behaviour of the <code>github</code> portgroup is leveraging
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      The <code>github</code> portgroup can leverage
</span>       GitHub's ability to create a distfile from a <code>git</code> tag or
       commit.  In this case, the <code>distname</code> is irrelevant and should
<span style='display:block; white-space:pre;background:#ffe0e0;'>-      not be set.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      not be set. To enable this feature, the following keyword should be used:
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      <programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+github.tarball_from archive</programlisting>
</span>     </para>
 
     <para>
<span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -132,30 +160,6 @@ version             20140401</programlisting>
</span>     </para>
   </section>
 
<span style='display:block; white-space:pre;background:#ffe0e0;'>-  <section xml:id="reference.portgroup.github.releases">
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-    <title>Distfile from a GitHub release</title>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-    <para>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      The <code>github</code> portgroup allows maintainers to easily configure
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      the distfiles when the project uses GitHub releases.  A release is the
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      best distfile candidate, and project maintainers should be encouraged to
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      use them.  To enable this feature, the following keyword must be used:
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      <programlisting>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-github.tarball_from releases</programlisting>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      By default, the <code>github</code> portgroup sets <code>distname</code>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      to:
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      <programlisting>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-distname            ${github.project}-${github.version}</programlisting>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      However, GitHub does not enforce any rule for release distfiles, so port
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      maintainers may need to override the <code>distname</code> as they would
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      do for other ports.
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-    </para>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-  </section>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span>   <section xml:id="reference.portgroup.github.downloads">
     <title>Distfile from a GitHub download</title>
 
<span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -179,16 +183,20 @@ github.tarball_from downloads</programlisting>
</span>     </para>
   </section>
 
<span style='display:block; white-space:pre;background:#ffe0e0;'>-  <section xml:id="reference.portgroup.github.archive">
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-    <title>Distfile from GitHub archive downloads</title>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+  <section xml:id="reference.portgroup.github.distfile">
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+    <title>Distfile from GitHub legacy tarball downloads</title>
</span> 
     <para>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-      Further still, many Github projects have automatically-generated archive
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      URLs that can be used for downloading distfiles.  This can be enabled via
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-      <code>archive</code> as follows:
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      Some ports still use GitHub's older automatically-generated tarball
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      URLs that can be used for downloading distfiles.  This is deprecated
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      since the contents of the tarballs can change in some circumstances,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      such as when the account name of the repository owner changes, and
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      this causes checksum mismatches. This mechanism should not be used in
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      new ports, and existing ports should switch away from it when they are
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+      updated to a newer version.
</span> 
       <programlisting>
<span style='display:block; white-space:pre;background:#ffe0e0;'>-github.tarball_from archive</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+github.tarball_from tarball</programlisting>
</span> 
     </para>
   </section>
</pre><pre style='margin:0'>

</pre>