[32715] epochs and the guide / was .. portfile-keywords.xml

[Chris Pickel]

On 11 Jan, 2008, at 19:03, markd at macports.org wrote:
>> On Jan 11, 2008, at 16:51, markd at macports.org wrote:
>>> - <para>If an epoch is used it must must never be
>>> decreased or reset
>>> - to zero, because this would always cause a port version
>>> comparison
>>> - to be incorrect after a port upgrade.</para>
>>> + <para>An epoch is not needed for most ports. If an epoch
>>> is used it
>>> + must never be decreased without updating the port's
>>> version number;
>>> + this will cause port version comparisons to be
>>> incorrect.</para>
>>
>> I was led to believe that an epoch should never be decreased, ever,
>> once it has been added to a portfile, even if the port's version is
>> increased. I understood that the epoch takes precedence over the
>> version. Do you have new information to the contrary?
>
> I don't think the FreeBSD Porter's handbook states it clearly, some  
> parts
> I'd interpret as agreeing with your understanding and other parts  
> seem to
> say otherwise.  But then I don't know for sure that MacPorts works the
> same anyway.
>
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-naming.html#MAKEFILE-NAMING-REVEPOCH
>
> I think discussion from someone (I forget who) some time ago made me  
> to
> think otherwise so I changed it when revising the section.  But I'm  
> not
> really sure.  If could someone could find out one way or another it  
> would
> be great to know for sure and document it.

For an example of how MacPorts does it, see port:543 (in proc  
get_outdated_ports). In pseudo-code, it says roughly:

   if current_epoch != available_epoch
     use epoch as basis for comparison
   else if current_version != available_version
     use version as basis for comparison
   else
     use revision as basis for comparison

This means that an epoch should never be removed, since if the epoch  
is different, it will always be used as the basis for comparison when  
listing outdated ports.

Some of the basis for confusion might come from macports.tcl:1923 (in  
proc upgrade), where the pseudo-code is roughly:

   if current_version != available_version
     use version as basis for comparison
   else
     use revision as basis for comparison
   if current_epoch < available_epoch
     upgrade anyway

Now that I've read it more thoroughly, this code actually *does* allow  
the epoch to be removed--eventually, once the updated version has been  
pushed out to everyone.

Hrm.

In other words, it seems that a port in which the epoch has been  
removed could still be upgraded (with e.g. `port upgrade active`), but  
would not be listed as outdated (and would not be upgraded with `port  
upgrade outdated`).

That's actually a bit of a mess and might deserve its own topic of  
discussion. For now, I think it should be stated that an epoch cannot  
be removed; this is the only case in which we can currently guarantee  
consistent behavior.

At the same time, we should change MacPorts' behavior to be  
consistent. I think the method from port(1) is better than the one  
from macports.tcl, since it's the only one in which we can guarantee  
upgrades correctly--even if it does force an extra line of cruft to  
hang around in Portfiles with epochs (all 20 of 'em!)


Chris