<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/d61bbbeb69eba8aaa27fe5e1c91fe387d4af1b57">https://github.com/macports/macports-guide/commit/d61bbbeb69eba8aaa27fe5e1c91fe387d4af1b57</a></p>
<pre style="white-space: pre; background: #F8F8F8"><span style='display:block; white-space:pre;color:#808000;'>commit d61bbbeb69eba8aaa27fe5e1c91fe387d4af1b57
</span>Author: Ryan Schmidt <ryandesign@macports.org>
AuthorDate: Sat Aug 22 04:19:15 2020 -0500
<span style='display:block; white-space:pre;color:#404040;'> Rewrite epoch section
</span>---
guide/xml/portfile-keywords.xml | 41 ++++++++++++++++++++++++++++++-----------
1 file changed, 30 insertions(+), 11 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 67a3fb6..6e91e08 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;'>@@ -167,21 +167,40 @@
</span> <term>epoch</term>
<listitem>
<span style='display:block; white-space:pre;background:#ffe0e0;'>- <para>An optional keyword (default value is 0) that must be used when
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- a port is updated to a version that is numerically less than the
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- previous version, for example 1.10 -> 1.2 or 20070928 -> 1.0.
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- Some Portfile authors have used large epoch values that look like a
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- date, but there is no reason to do so. The epoch is simply an unsigned
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- integer, and the only requirement is that it never be decreased. Remember
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- that once set, it can never be removed because it takes precedence over
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- version and revision.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>An optional integer (the default is <literal>0</literal>) that
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ must be increased when a port is updated to a version that appears
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ (according to the <code>vercmp</code> procedure's version number
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ comparison algorithm) to be less than the previous version. For example,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ updating from <literal>2.0-rc1</literal> to <literal>2.0</literal>, or
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ from <literal>1.10</literal> to <literal>1.2</literal>, or from
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <literal>20070928</literal> to <literal>1.0</literal>.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>The purpose of increasing the epoch is to cause MacPorts to
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ consider a port to be outdated, even if that wouldn't otherwise be the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ case due to the specific version numbers. Don't set the epoch unless
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ it's required. In most ports, the version number advances according to
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ the normal dotted-decimal sequence, so most ports will never have a need
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ to set the epoch.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Some Portfile authors have used large epoch values that look like
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ dates in YYYYMMDD format (e.g., <literal>20091231</literal>). When it is
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ necessary to increase the epoch in such ports, the new epoch can be set
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ to the current date. It is not recommended to use this format when
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ adding an epoch to a port that does not already have one; instead, just
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ set the epoch to <literal>1</literal>, and when needing to increase an
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ existing small epoch, increase it by 1.</para>
</span>
<programlisting>epoch 1</programlisting>
<note>
<span style='display:block; white-space:pre;background:#ffe0e0;'>- <para>An epoch is not needed for most ports. If a port's version
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- numbers advance in normal dotted-decimal sequence, there is no reason
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- to add an epoch.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>A port's epoch can never be decreased. Removing the epoch from
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ the port would decrease it to its default value of
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <literal>0</literal>, so once added to a port the epoch can also never
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ be removed. When adding an epoch, take extra care to ensure that it is
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ necessary, since a mistakenly added epoch cannot be undone. In
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Portfiles that have subports with different software versions,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ consider whether the epoch needs to be increased in all subports or
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ only in some of them.</para>
</span> </note>
</listitem>
</varlistentry>
</pre><pre style='margin:0'>
</pre>