Is this on the wiki? Also, adding if a port: dependency is changed requires a revision bump would be good to list for completeness, e.g. https://github.com/macports/macports-ports/commit/9e9d40fea3f205523d842ff78e5ca8063cffbaf0 .
> On Jun 25, 2020, at 10:00 PM, Ryan Schmidt <[email protected]> wrote: > > 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. > >
