<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>