Reminders about revisions and when to increase them

[Ryan Schmidt]

Hi all,

I want to remind everyone about when you should increase a port's revision and when you should not. Please don't increase revisions unnecessarily because it wastes time on our build servers and on users systems.


You SHOULD increase a port's revision if a user who already has the port installed should be prompted to reinstall the port with those changes. The most frequent reason is if you are changing the files installed by the port. Examples:

* Adding a dependency on a library that the port would use opportunistically
* Linking with a new version of a dependency's library
* Adding a patchfile that changes files that will be installed
* Adding documentation files
* Renaming or relocating files or directories that are installed
* Removing a variant
* Adding a variant to the port's default_variants


You SHOULD increase a port's revision if you are adding or removing library or runtime dependencies, because those are recorded in the registry. Examples:

* A port X requires libpng but this was not declared in X's portfile. If the user happened to have libpng installed already then X builds fine but in the registry MacPorts has not recorded that X uses libpng because it doesn't know that. As a result, the user would be able to uninstall libpng and MacPorts would not warn the user that this would break X. Increase the revision when adding the dependency on libpng so that the user must reinstall the port so that the correct dependencies get into the registry.


You SHOULD NOT increase a port's revision if your change will not change anything for users who already have the port installed. Examples:

* Setting or changing the port's license
* Fixing a build failure, for example adding a build dependency like pkgconfig if the port would fail to build without it
* Removing an unneeded build dependency
* Adding a new non-default variant
* Removing a variant from the port's default_variants (variants are preserved on upgrades)
* Fixing a typo in a comment in the Portfile
* Changing the whitespace of the Portfile


Subports are a complication. A single Portfile might define several subports. Think carefully when you change revisions which subports the change should apply to.

For example, a simple python module port has subports for several versions of python but they are all for the same version of that python module. It makes sense to have a single version line and a single revision line beneath that and to increase the revision for all of the subports at the same time. But other python module ports may be more complicated, offering a newer version of the python module on newer python versions and an older version of the module on older python versions. In that case there are two version lines and two revision lines, and you must think carefully about which of the two revision lines, or both, should be increased for any particular change. For example if you are adding a missing dependency to the new version of the python module but that dependency is not used by the old version, you would only be increasing the revision of the new version.

In "regular" ports that use subports (i.e. not python/php/perl modules), don't forget that the main port is a subport too. In a portfile that has subports, just because there's a version line at the top of the portfile doesn't mean you should necessarily add a revision line right below it. Instead, define separate revision lines for each subport, including the main port:

if {${subport} eq ${name} {
    revision        0
    ...
}

subport foo {
    revision        0
    ...

}

subport bar {
    revision        0
    ...

}

Do include a "revision 0" line, even though that is the default. That way it is easy for you and other developers who might have need to modify your port to see exactly where revisions could be set. It also makes it easier for tools that automatically bump revisions to do so correctly.


Many developers seem to have been under the impression that it is necessary to increase the revision in order to get the buildbot to retry a build. That is not the case.

Every commit sends a notification to the buildbot. The buildbot doesn't look at the content of the commit except to determine which ports' source directories were modified. It updates to the latest version of macports-ports and then checks if an archive already exists on the right server for the those ports. If not, it builds and uploads them. The archive name contains the port's name, version, revision, variants, platform name and version, and archs, so if any of those changes (including if the port's default_variants have changed) a new build will be started.

"The right server" means the public server for ports whose license indicates that they are distributable and a private server for ports that are not distributable. If a commit is made that changes a port's distributability, that changes what "the right server" is and so it will trigger a build and upload to the new right server if needed.


If you increase a port's revision unnecessarily, you should not revert that change because some users may already have installed the port with the new revision.