Policies/Dependency Changes and CI

Overview of the problem

KDE makes use of a Continuous Integration system to regularly build and test our software as we develop it.

The CI system is maintained by the KDE System Administration team, who are in charge of procuring the build and runtime dependencies our software required from the CI system environment.

If a required dependency is not provided by the CI system environment, the CI system fails to be able to usefully build or test the affected software.

This creates needs for developers to take care in changing software dependency, and for system administrators to try and procure newly-required dependencies in a reasonable timeframe.

Sorting our wants

There's a couple of things we want out of our development process and how the CI system fits into it. Here's a list:

We want to have a working CI system that gives us useful results.

We want to have developer flexibility in terms of using and catering to the latest external dependencies of our software.

We want the master branches to be realistically buildable by other devs, meaning they need to be able to reasonably procure required build dependencies.

We want to keep the quality of the tips of our master development branches high.

These wants can be in conflict with each other. For example, "keep the quality of HEAD high" can require dragging in very recenty dependencies when our and the external code need to act in concern to address a problem. On the other hand, "have a working CI system" and "realistically buildable" mean avoiding a dependency no one can get their hands on, as the sysadmin team needs time to update the CI system environment and the number of people who can participate in our development process shrinks otherwise.

Returning to "keep the quality of HEAD high" allows us to make some progress in sorting these wants. A cornerstone of our efforts to do so is to consider regression-type defects in our software as more important than newly-identified defects: Things that worked before should keep working. Breaking the build for developers or the CI system is to be considered a regression, and should therefore be avoided.

This means the sysadmin team needs to be informed of and consulted on dependency changes ahead of time.

The process

The protocol for informing the sysadmin team of dependency changes is documented in the following, strongly recommended guidelines. In turn, the sysadmin team equally promises to follow them for abiding projects.

Dependency changes for software covered by the CI system should be submitted through code review and the sysadmin team should be subscribed to these code reviews (on Phabricator, add the "Sysadmin" group to reviewers). If you can see a dep change on the horizon but aren't ready to submit the code change yet, it's good to inform sysadmin ahead of time to give more prep time and speed up the process.

The sysadmin team should provide input in the review within two weeks. If it is for some reason unable to do so (staff shortages, etc.) it should keep the community appraised of the situation.

In addition to the normal review process, submitting the dependency change to the code repository is allowed under these guidelines:
- ... when the sysadmin team gives a green light by accepting the review.
- ... when the sysadmin team did not provide input within two weeks but the change was generally accepted in review (all participants are asked to give consideration to the CI factor).

If the sysadmin team did respond within two weeks but did not accept the change, it can be submitted to the code repository anyway one month after filing the review request if the change was generally accepted in review.

If neither the sysadmin team nor anyone else respond to the code review within one month, it can be submitted anyway.

In general, the sysadmin team should try and procure new dependencies within one month. If it is for some reason unable to do, the reasons should be clearly explained in the associated code review.

Under special circumstances that do not fit this framework (e.g. urgency prior to a freeze), exception requests should be raised in an established venue such as release-team or kde-core-devel. In general, changes that fellow developers can't be convinced of are probably not a good idea.

While maintainers should retain ultimate control over their product, the above guidelines reflect that sysadmin needs to be given consideration to keep CI going for mutual benefit, which the community cares greatly about. By following them the sysadmin team is given an opportunity to chime in and slow down the process if needed. It should be understood that not only is sysadmin in their right to remove projects from CI that don't follow them (as they cannot be reasonably supported), but it's also considered rude. As always, maintainers are implored to use common sense in caring for both the developer and user audiences of their product.