Tue Aug 11 20:32:59 2020 UTC ()
fixes.html: Expand Github versioning guide

Split section on Github commits into two:

1. Commits before the first release (recommend 0.0.0.N)
2. Commits between releases (use git describe --tags)

Also clean up indentation and remove zero-width space chars that were not
rendering properly.


(bacon)
diff -r1.158 -r1.159 pkgsrc/doc/guide/files/fixes.xml
cvs diff -r1.158 -r1.159 pkgsrc/doc/guide/files/fixes.xml (expand / switch to unified diff)

--- pkgsrc/doc/guide/files/fixes.xml 2020/06/18 20:30:12 1.158
+++ pkgsrc/doc/guide/files/fixes.xml 2020/08/11 20:32:58 1.159
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1<!-- $NetBSD: fixes.xml,v 1.158 2020/06/18 20:30:12 wiz Exp $ --> 1<!-- $NetBSD: fixes.xml,v 1.159 2020/08/11 20:32:58 bacon Exp $ -->
2 2
3<chapter id="fixes"> <?dbhtml filename="fixes.html"?> 3<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
4<title>Making your package work</title> 4<title>Making your package work</title>
5 5
6<sect1 id="general-operation"> 6<sect1 id="general-operation">
7 <title>General operation</title> 7 <title>General operation</title>
8 8
9 <para>One appealing feature of pkgsrc is that it runs on many 9 <para>One appealing feature of pkgsrc is that it runs on many
10 different platforms. As a result, it is important to ensure, 10 different platforms. As a result, it is important to ensure,
11 where possible, that packages in pkgsrc are portable. This 11 where possible, that packages in pkgsrc are portable. This
12 chapter mentions some particular details you should pay 12 chapter mentions some particular details you should pay
13 attention to while working on pkgsrc.</para> 13 attention to while working on pkgsrc.</para>
14 14
@@ -1007,68 +1007,96 @@ FETCH_MESSAGE+= "manually from "${MASTER @@ -1007,68 +1007,96 @@ FETCH_MESSAGE+= "manually from "${MASTER
1007 1007
1008 <sect2 id="build.fetch.github"> 1008 <sect2 id="build.fetch.github">
1009 <title>Packages hosted on github.com</title> 1009 <title>Packages hosted on github.com</title>
1010 1010
1011 <para>Helper methods exist for packages hosted on github.com which 1011 <para>Helper methods exist for packages hosted on github.com which
1012 will often have distfile names that clash with other packages, for 1012 will often have distfile names that clash with other packages, for
1013 example <filename>1.0.tar.gz</filename>. Use one of the three recipes 1013 example <filename>1.0.tar.gz</filename>. Use one of the three recipes
1014 from below:</para> 1014 from below:</para>
1015 1015
1016 <sect3 id="build.fetch.github.tag"> 1016 <sect3 id="build.fetch.github.tag">
1017 <title>Fetch based on a tagged release</title> 1017 <title>Fetch based on a tagged release</title>
1018 1018
1019 <para>If your distfile URL looks similar to 1019 <para>If your distfile URL looks similar to
1020 <literal>https://github.com/username/exampleproject/archive/v1.0.zip</literal>, 1020 <literal>https://github.com/username/example/archive/v1.0.zip</literal>,
1021 then you are packaging a tagged release.</para> 1021 then you are packaging a tagged release.</para>
1022 1022
1023<programlisting> 1023<programlisting>
1024DISTNAME= exampleproject-1.0 1024DISTNAME= example-1.0
1025MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} 1025MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
1026#GITHUB_PROJECT= # can be omitted if same as DISTNAME 1026#GITHUB_PROJECT= example # can be omitted if same as DISTNAME
1027GITHUB_TAG= v${PKGVERSION_NOREV} 1027GITHUB_TAG= v${PKGVERSION_NOREV}
1028EXTRACT_SUFX= .zip 1028EXTRACT_SUFX= .zip
1029</programlisting> 1029</programlisting>
1030 1030
1031 </sect3> 1031 </sect3>
1032 1032
1033 <sect3 id="build.fetch.github.commit"> 1033 <sect3 id="build.fetch.github.commit.prerelease">
1034 <title>Fetch based on a specific commit</title> 1034 <title>Fetch based on a specific commit before the first release</title>
1035 1035
1036 <para>If your distfile URL looks similar to 1036 <para>If your distfile looks similar to
1037 <literal>https://github.com&#x200B;/example&#x200B;/example&#x200B;/archive&#x200B;/988881adc9fc3655077dc2d4d757d480b5ea0e11.tar.gz</literal>, 1037 <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit before the first
1038 then you are packaging a specific commit not tied to a 1038 release, then set the package version to 0.0.0.N, where N is the number
1039 release.</para> 1039 of commits to the repository, and set GITHUB_TAG to the commit hash.
 1040 This will (almost) ensure that the first tagged release will have a
 1041 version greater than this one so that package upgrades will function
 1042 properly.</para>
1040 1043
1041<programlisting> 1044<programlisting>
1042DISTNAME= example-1.0 1045DISTNAME= example-0.0.0.347
1043MASTER_SITES= ${MASTER_SITE_GITHUB:=example/} 1046MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
1044#GITHUB_PROJECT= # can be omitted if same as DISTNAME 1047#GITHUB_PROJECT= example # can be omitted if same as DISTNAME
1045GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11 1048GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11
1046</programlisting> 1049</programlisting>
 1050 </sect3>
 1051
 1052 <sect3 id="build.fetch.github.commit.postrelease">
 1053 <title>Fetch based on a specific commit after a release</title>
1047 1054
 1055 <para>If your distfile looks similar to
 1056 <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit after a release,
 1057 then include the last release version and the commit count since that
 1058 release in the package version and set GITHUB_TAG to the commit hash.
 1059 The latest release and commit count are shown in the output of
 1060 "git describe --tags":
 1061 </para>
 1062
 1063<screen>
 1064# git clone https://github.com/username/example
 1065# cd example
 1066# git describe --tags
 10671.2.3-5-g988881a
 1068</screen>
 1069
 1070<programlisting>
 1071DISTNAME= example-1.2.3.5
 1072MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
 1073#GITHUB_PROJECT= example # can be omitted if same as DISTNAME
 1074GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11
 1075</programlisting>
1048 </sect3> 1076 </sect3>
1049 1077
1050 <sect3 id="build.fetch.github.release"> 1078 <sect3 id="build.fetch.github.release">
1051 <title>Fetch based on release</title> 1079 <title>Fetch based on release</title>
1052 1080
1053 <para>If your distfile URL looks similar to 1081 <para>If your distfile URL looks similar to
1054 <literal>https://github.com&#x200B;/username/exampleproject&#x200B;/releases&#x200B;/download&#x200B;/rel-1.6&#x200B;/offensive-1.6.zip</literal>, 1082 <literal>https://github.com/username/example/releases/download/rel-1.6/offensive-1.6.zip</literal>,
1055 then you are packaging a release.</para> 1083 then you are packaging a release.</para>
1056 1084
1057<programlisting> 1085<programlisting>
1058DISTNAME= offensive-1.6 1086DISTNAME= offensive-1.6
1059PKGNAME= ${DISTNAME:S/offensive/proper/} 1087PKGNAME= ${DISTNAME:S/offensive/proper/}
1060MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} 1088MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
1061GITHUB_PROJECT= exampleproject 1089GITHUB_PROJECT= example
1062GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME} 1090GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME}
1063EXTRACT_SUFX= .zip 1091EXTRACT_SUFX= .zip
1064</programlisting> 1092</programlisting>
1065 </sect3> 1093 </sect3>
1066 </sect2> 1094 </sect2>
1067</sect1> 1095</sect1>
1068 1096
1069 1097
1070<sect1 id="fixes.configure"> 1098<sect1 id="fixes.configure">
1071 <title>The <emphasis>configure</emphasis> phase</title> 1099 <title>The <emphasis>configure</emphasis> phase</title>
1072 1100
1073 <sect2 id="fixes.libtool"> 1101 <sect2 id="fixes.libtool">
1074 <title>Shared libraries - libtool</title> 1102 <title>Shared libraries - libtool</title>