Tue Dec 6 01:37:11 2022 UTC ()
fixes.xml: add more explanatory detail about GITHUB_TAG use


(gutteridge)
diff -r1.182 -r1.183 pkgsrc/doc/guide/files/fixes.xml
cvs diff -r1.182 -r1.183 pkgsrc/doc/guide/files/fixes.xml (expand / switch to unified diff)

--- pkgsrc/doc/guide/files/fixes.xml 2022/08/08 01:54:32 1.182
+++ pkgsrc/doc/guide/files/fixes.xml 2022/12/06 01:37:11 1.183
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1<!-- $NetBSD: fixes.xml,v 1.182 2022/08/08 01:54:32 gutteridge Exp $ --> 1<!-- $NetBSD: fixes.xml,v 1.183 2022/12/06 01:37:11 gutteridge 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
@@ -1053,26 +1053,30 @@ FETCH_MESSAGE+= "manually from "${MASTER @@ -1053,26 +1053,30 @@ FETCH_MESSAGE+= "manually from "${MASTER
1053 1053
1054 <para>If your distfile URL looks similar to 1054 <para>If your distfile URL looks similar to
1055 <literal>https://github.com/username/example/archive/v1.0.zip</literal>, 1055 <literal>https://github.com/username/example/archive/v1.0.zip</literal>,
1056 then you are packaging a tagged release.</para> 1056 then you are packaging a tagged release.</para>
1057 1057
1058<programlisting> 1058<programlisting>
1059DISTNAME= example-1.0 1059DISTNAME= example-1.0
1060MASTER_SITES= ${MASTER_SITE_GITHUB:=username/} 1060MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
1061#GITHUB_PROJECT= example # can be omitted if same as DISTNAME 1061#GITHUB_PROJECT= example # can be omitted if same as DISTNAME
1062GITHUB_TAG= v${PKGVERSION_NOREV} 1062GITHUB_TAG= v${PKGVERSION_NOREV}
1063EXTRACT_SUFX= .zip 1063EXTRACT_SUFX= .zip
1064</programlisting> 1064</programlisting>
1065 1065
 1066 <para>Here, DISTNAME combined with use of GITHUB_TAG leads the
 1067 file fetching infrastructure to save the resulting file locally as
 1068 <literal>example-1.0.zip</literal>.</para>
 1069
1066 </sect3> 1070 </sect3>
1067 1071
1068 <sect3 id="build.fetch.github.commit.prerelease"> 1072 <sect3 id="build.fetch.github.commit.prerelease">
1069 <title>Fetch based on a specific commit before the first release</title> 1073 <title>Fetch based on a specific commit before the first release</title>
1070 1074
1071 <para>If your distfile looks similar to 1075 <para>If your distfile looks similar to
1072 <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit before the first 1076 <literal>https://github.com/username/example/archive/988881adc9fc3655077dc2d4d757d480b5ea0e11</literal> and is from a commit before the first
1073 release, then set the package version to 0.0.0.N, where N is the number 1077 release, then set the package version to 0.0.0.N, where N is the number
1074 of commits to the repository, and set GITHUB_TAG to the commit hash. 1078 of commits to the repository, and set GITHUB_TAG to the commit hash.
1075 This will (almost) ensure that the first tagged release will have a 1079 This will (almost) ensure that the first tagged release will have a
1076 version greater than this one so that package upgrades will function 1080 version greater than this one so that package upgrades will function
1077 properly.</para> 1081 properly.</para>
1078 1082