<pre style='margin:0'>
Ryan Schmidt (ryandesign) pushed a commit to branch master
in repository macports-guide.
</pre>
<p><a href="https://github.com/macports/macports-guide/commit/6b759a3792c5ed57825c41b606faed6c4d95b3ca">https://github.com/macports/macports-guide/commit/6b759a3792c5ed57825c41b606faed6c4d95b3ca</a></p>
<pre style="white-space: pre; background: #F8F8F8"><span style='display:block; white-space:pre;color:#808000;'>commit 6b759a3792c5ed57825c41b606faed6c4d95b3ca
</span>Author: Ryan Schmidt <ryandesign@macports.org>
AuthorDate: Sat Aug 22 04:18:58 2020 -0500
<span style='display:block; white-space:pre;color:#404040;'> Rewrite revision section
</span>---
guide/xml/portfile-keywords.xml | 94 +++++++++++++++++++++++++++++++++++++----
1 file changed, 86 insertions(+), 8 deletions(-)
<span style='display:block; white-space:pre;color:#808080;'>diff --git a/guide/xml/portfile-keywords.xml b/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;color:#808080;'>index db9748b..67a3fb6 100644
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>--- a/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>+++ b/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -72,14 +72,92 @@
</span> <term>revision</term>
<listitem>
<span style='display:block; white-space:pre;background:#ffe0e0;'>- <para>Optional keyword (default is 0) that is used to track port
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- revisions. It should not be incremented for port revisions unless it
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- would benefit users to upgrade an installed port, and cleared when the
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- port is updated to a newer version.</para>
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>-
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- <para>It should be used if a bug in the Portfile was found and all
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- installations of this port have to be updated. If the change only
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- affects new installations, there is no need to increase it.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>An optional integer (the default is <literal>0</literal>) that is
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ incremented when a port is updated independently of the version of the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ software. The revision line usually follows the version line.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>In Portfiles that have subports, it is often appropriate for each
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ subport (including the main port) to have a separate revision line.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ (This does not usually apply to Portfiles for Perl, PHP, Python, or Ruby
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ modules which create numerous similar subports for the same version of
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ the software.)</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>It is recommended to set the revision in all ports, even if the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ revision is 0. This makes it easier for other developers to see where to
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ increase the revision in your port, should that need arise. This is
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ especially helpful for Portfiles that have subports.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>When increasing the revision in a Portfile with subports, consider
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ carefully which of the subports (possibly including the main port) need
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ to have their revisions increased.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>When increasing the revision in a Portfile that does not have any
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ revision lines yet, take a moment to check if the Portfile has
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ subports.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Just like when a port's version increases, a port is considered
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ outdated when its revision increases. To avoid causing users to rebuild
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ports unnecessarily, don't increase the revision unless doing so would
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ result in a change for users who already have the ports
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ installed.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Some examples of situations in which a port's revision should be
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ increased:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <itemizedlist>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>changing configure arguments or build flags or any other
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ change that will cause the installed files to be different</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>installing additional files, such as documentation, or
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ removing any files which had previously been installed</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>changing the names or locations of any installed files</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>adding a dependency to depends_lib or depends_run</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>a library dependency's install_name has changed</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>removing a variant that a user might have installed</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>adding a variant name to default_variants</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </itemizedlist>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Some examples of situations in which a port's revision should not
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ be increased:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <itemizedlist>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>fixing a build failure</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>adding a dependency to depends_fetch, depends_extract,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ depends_build, or depends_test</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>setting or changing the port's license</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>adding a new non-default variant</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>removing a variant name from default_variants</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>changing comments or whitespace in the Portfile</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>any other change to the Portfile that does not change the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ files it installs</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </itemizedlist>
</span>
<programlisting>revision 1</programlisting>
</listitem>
</pre><pre style='margin:0'>
</pre>