epochs and the guide

[markd at macports.org]

>or 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,

I changed the text to this based on what you said about current behavior. 
Let me know if it needs adjusting.

----------
An epoch is not needed for most ports. If an epoch is used it must never
be decreased or removed even when a port's version is updated; this would
cause port version comparisons to be incorrect since epochs take
precedence over versions once epochs have been used.
----------

Mark