macports-guide/guide/xml/portgroup-github.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN"
"http://docbook.org/xml/5.0/dtd/docbook.dtd">
<section xml:id="reference.portgroup.github" xmlns:xlink="http://www.w3.org/1999/xlink">

  <title>PortGroup github</title>

  <para>The <code>github</code> portgroup allows for efficient porting of
  software hosted on GitHub.</para>

  <section xml:id="reference.portgroup.github.description">
    <title>Description</title>

    <para>
      This portgroup greatly simplifies the porting of software hosted on
      GitHub.  Provided a GitHub repository author follows common GitHub
      practices, a port can be almost fully configured simply by declaring the
      repository coordinates.  The <code>github</code> portgroup is indeed
      capable of configuring, amongst other things:

      <itemizedlist>
        <listitem>
          <para>The port <code>name</code>.</para>
        </listitem>
        <listitem>
          <para>The port <code>version</code>.</para>
        </listitem>
        <listitem>
          <para>The <code>distfiles</code> (if the project uses GitHub
          releases).</para>
        </listitem>
        <listitem>
          <para>The <code>livecheck</code> parameters.</para>
        </listitem>
      </itemizedlist>
    </para>
  </section>

  <section xml:id="reference.portgroup.github.setup">
    <title>Setting up the GitHub repository coordinates</title>

    <para>
      The main port configuration is triggered by the usage of the
      <code>github.setup</code> keyword:

      <programlisting>
PortGroup           github 1.0
github.setup        author project version [tag_prefix]</programlisting>
    </para>

    <para>
      By default, the port <code>name</code> will be set to the GitHub project
      name (<code>project</code>) and <code>version</code> will be set to the
      GitHub project <code>version</code>.  The port name can be overridden by
      using the <code>name</code> keyword.
    </para>

    <para>
      The <code>tag_prefix</code> is optional, and it's used to specify a prefix
      to use when constructing the tag name.  If, for example, the project uses
      tags such as <code>v1.0.0</code>, then the <code>tag_prefix</code> should
      be set to <code>v</code>, as in the following example:

      <programlisting>
github.setup        author project version v</programlisting>
    </para>
  </section>

  <section xml:id="reference.portgroup.github.distfilestrategy">
    <title>Choosing a distfile strategy</title>

    <para>
      GitHub, and as a consequence the <code>github</code> portgroup, offers
      multiple mechanisms to get a distfile:

      <itemizedlist>
        <listitem>
          <para>Distfile from a <code>git</code> commit or tag.</para>
        </listitem>
        <listitem>
          <para>
            Distfile from a GitHub <link
            xlink:href="https://github.com/blog/1547-release-your-software">release</link>.
          </para>
        </listitem>
        <listitem>
          <para>
            Distfile from a GitHub <link
            xlink:href="https://github.com/blog/1302-goodbye-uploads">download</link>.
          </para>
        </listitem>
        <listitem>
          <para>
            Distfile from Github legacy auto-generated tarball downloads
          </para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      The default behaviour of the portgroup is to use GitHub releases.
      However, not all projects offer releases, so it may be necessary to
      instead use an automatically generated distfile from a
      <code>git</code> commit or tag.
    </para>
  </section>

  <section xml:id="reference.portgroup.github.releases">
    <title>Distfile from a GitHub release</title>

    <para>
      The <code>github</code> portgroup allows maintainers to easily configure
      the distfiles when the project uses GitHub releases.  A release is the
      best distfile candidate, and project maintainers should be encouraged to
      use them.  To enable this feature, the following keyword should be used:

      <programlisting>
github.tarball_from releases</programlisting>

      By default, the <code>github</code> portgroup sets <code>distname</code>
      to:

      <programlisting>
distname            ${github.project}-${github.version}</programlisting>

      However, GitHub does not enforce any rule for release distfiles, so port
      maintainers may need to override the <code>distname</code> as they would
      do for other ports.
    </para>
  </section>

  <section xml:id="reference.portgroup.github.archive">
    <title>Distfile from tag or commit</title>

    <para>
      The <code>github</code> portgroup can leverage
      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
      not be set. To enable this feature, the following keyword should be used:

      <programlisting>
github.tarball_from archive</programlisting>
    </para>

    <para>
      If the project's developers do not tag their releases, they should be
      encouraged to do so.  Until they do, or in the case in which an untagged
      development version has to be used, port maintainers have the possibility
      of specifying a <code>git</code> commit hash and manually set the
      <code>version</code> field.  If the project does not assign version
      numbers the port maintainer has to define one.  Such versions typically
      format the date of the chosen commit using the <code>YYYYMMDD</code>
      pattern.  If, for example, the port maintainer decides to use a changeset
      with the hash <code>0ff25277c3842598d919cd3c73d60768</code>, committed on
      April 1, 2014, then the following would be used:

      <programlisting>
github.setup        someone someproject 0ff25277c3842598d919cd3c73d60768
version             20140401</programlisting>
    </para>
  </section>

  <section xml:id="reference.portgroup.github.downloads">
    <title>Distfile from a GitHub download</title>

    <para>
      Older projects use the discontinued <link
      xlink:href="https://github.com/blog/1302-goodbye-uploads">downloads</link>
      service.  New GitHub downloads can no longer be created, but old ones are
      still available.
    </para>

    <para>
      If the project doesn't have GitHub releases but does have GitHub
      downloads, they can be used using the following keyword:

      <programlisting>
github.tarball_from downloads</programlisting>

      Since GitHub doesn't enforce any naming rules for downloads, the portgroup
      can only provide a sensible default value for <code>distname</code>, which
      can be overridden if necessary.
    </para>
  </section>

  <section xml:id="reference.portgroup.github.distfile">
    <title>Distfile from GitHub legacy tarball downloads</title>

    <para>
      Some ports still use GitHub's older automatically-generated tarball
      URLs that can be used for downloading distfiles.  This is deprecated
      since the contents of the tarballs can change in some circumstances,
      such as when the account name of the repository owner changes, and
      this causes checksum mismatches. This mechanism should not be used in
      new ports, and existing ports should switch away from it when they are
      updated to a newer version.

      <programlisting>
github.tarball_from tarball</programlisting>

    </para>
  </section>


  <section xml:id="reference.portgroup.github.submodule">
    <title>Using repositories with git submodules</title>

    <para>
      If the project uses <code>git</code> submodules, some projects' tag- or
      commit-based distfiles will not contain all the necessary files.  Once
      again, the best distfile candidate (if available) is a distfile from
      GitHub releases, as described in the previous sections.  However, in the
      case a project doesn't provide any other alternative, a project using
      submodules can be successfully retrieved by fetching the sources using
      <code>git</code> and then using a <code>post-fetch</code> to initialize
      the submodules:

      <programlisting>
fetch.type          git

post-fetch {
    system -W ${worksrcpath} "git submodule update --init"
}</programlisting>
    </para>
  </section>
</section>