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.
