From 2316b460bdc2013bcff9bd442f69ec4021f9c669 Mon Sep 17 00:00:00 2001
From: Mathieu Arnold <mat@FreeBSD.org>
Date: Mon, 14 Aug 2017 14:59:20 +0000
Subject: [PATCH] Add another example about GitHub projects with no versions.

Sponsored by:	Absolight
---
 .../porters-handbook/makefiles/chapter.xml    | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
index 4930352f95..e3fcfc1190 100644
--- a/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
@@ -2516,6 +2516,39 @@ USE_GITHUB=	yes</programlisting>
 	  <varname>${WRKDIR}/foo-1.0.2</varname>.</para>
       </example>
 
+      <example xml:id="makefile-master_sites-github-ex4">
+	<title>Using <varname>USE_GITHUB</varname> When Upstream Does
+	  Not Use Versions</title>
+
+	<para>If there never was a version upstream, do not invent one
+	  like <literal>0.1</literal> or <literal>1.0</literal>.
+	  Create the port with a <varname>DISTVERSION</varname> of
+	  <literal>g<replaceable>YYYY</replaceable><replaceable>MM</replaceable><replaceable>DD</replaceable></literal>,
+	  where <literal>g</literal> is for
+	  <application>Git</application>, and
+	  <literal><replaceable>YYYY</replaceable><replaceable>MM</replaceable><replaceable>DD</replaceable></literal>
+	  represents the date the commit referenced in
+	  <varname>GH_TAGNAME</varname>.</para>
+
+	<programlisting>PORTNAME=	bar
+DISTVERSION=	g20140411
+
+USE_GITHUB=	yes
+GH_TAGNAME=	c472d66b</programlisting>
+
+	<para>This creates a versioning scheme that increases over
+	  time, and that is still before version <literal>0</literal>
+	  (see <xref linkend="makefile-versions-ex-pkg-version"/> for
+	  details on &man.pkg-version.8;):</para>
+
+	<screen>&prompt.user; <userinput>pkg version -t g20140411 0</userinput>
+&lt;</screen>
+
+	<para>Which means using <varname>PORTEPOCH</varname> will not
+	  be needed in case upstream decides to cut versions in the
+	  future.</para>
+      </example>
+
       <sect3 xml:id="makefile-master_sites-github-multiple">
 	<title>Fetching Multiple Files from GitHub</title>