Reminders about revisions and when to increase them

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Reminders about revisions and when to increase them

ryandesign2
Administrator
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.

Reply | Threaded
Open this post in threaded view
|

Re: Reminders about revisions and when to increase them

Blair Zajac
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 <[hidden email]> 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.
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Reminders about revisions and when to increase them

ryandesign2
Administrator


On Jun 28, 2020, at 00:38, Blair Zajac wrote:

> Is this on the wiki?

The guide is where things should be documented. I don't know if all of this is already there. I'm guessing not, since there seems to have been so much confusion about it.

I don't spend as much time as maybe I should in updating the guide. For one thing, it's written in docbook XML, which is a pain to modify. Rainer worked on converting it to asciidoc which should be easier to edit once that conversion is finalized. The other problem is that I don't like most of the guide content and its organization so it's very hard to go modify or add just one part since in the process of doing that I see everything else that's wrong and become overwhelmed.


> 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 .

Well yeah. Changing a dependency is the same as adding a dependency and removing another, which change the registry, which requires a revbump.