Title: Encourage Continuous Integration and Merge Request based Collaboration for Debian packages
DEP: 18
State: DRAFT
Date: 2025-07-14
Drivers: Otto Kekäläinen <otto@debian.org>
URL: https://dep.debian.org/deps/dep18
Source: https://salsa.debian.org/dep-team/deps/-/blob/master/web/deps/dep18.wdwn
License: CC-BY-4.0
Abstract:
 This document summarizes the principles Debian packages should follow
 to encourage collaboration in package maintenance while using code reviews
 and continuous integration testing.

1. Maintain Debian Packaging Sources in Git on Salsa

All Debian package source code should be maintained using the git version control system, and hosted on salsa.debian.org.

Avoid using the official Debian repositories as a source version control system. Use a git repository instead. Git commits may be frequent and even happen multiple times an hour, while uploads to Debian should be infrequent with less than one new uploaded version per week. Naturally a serious regression should be fixed promptly, but a developer uploading the same package several times a day should reconsider their quality assurance practices.

Leveraging git's capabilities for distributed hosting, the package source code may also be hosted in parallel on other platforms. Packages that collaborate closely with their upstreams may for example benefit from pushing and pulling git commits to and from the upstream project repository hosted elsewhere. However, collaborators should be able to contribute to Debian packaging using their Salsa account on Salsa, and not required to have an account on e.g. GitHub or GitLab.

Git usage should follow universal conventions, such as writing proper git commit messages that explain why a change was made, and scoping individual commits as self-standing changes that can be cherry-picked or reverted if needed. Most importantly, potential collaborators should be able to review packaging code history using commands such as git log and git blame or equivalent graphical tools.

If these practices are followed such that all changes made are readily accessible in git, then the package changelog need only mention user-facing changes, instead of all changes, which was the historical practice before widespread use of VCS.

The default git branch (HEAD) as configured in Salsa should be the primary target for code submissions and protected from git force-pushes to ensure all collaborators have a consistent view of the git history. The Vcs-Git field in the control file should point to the packaging repository is described in the Debian Policy section 5.6.26. The use of debian/latest as the default branch name and other git branch and tag naming conventions appropriate for Debian packaging repositories are described in DEP-14.

If upstream uses git, the Repository field in upstream/metadata may point to the upstream git repository URL as described in DEP12 so that packaging tools can automate the adding the git remote upstreamvcs.

Use of git-buildpackage is recommended as the most widely used tool for maintaining Debian source packages in git. It is also the only option currently compatible with importing from all the various upstreams with software included in Debian. When using git-buildpackage, repositories should have a gbp.conf that defines the release conventions for the specific upstream, such as if releases are expected to be cryptographically signed, and what the upstream release git tag format is. Additional options may be configured in the file so that collaborators can run the various gbp commands without needing to pass extra options.

Packages should use gbp pq to make maintaining and testing upstream patches easy. Tracking the origin of changes and deciding what to include or drop is tightly coupled with code reviews and collaboration for Debian packages, and is much easier if all patches consistently use the Forwarded: header in DEP-3. If an improvement is not sent upstream, the patch description should clearly state why it needs to be stay Debian-specific.

If the package has custom tooling or processes, documenting them in README.source(.md) makes it easy for collaborators to learn how the package is to be built and maintained. Maintainers should keep the metadata and documentation current to facilitate contributions, while contributors should follow the conventions diligently and strive to make high-quality contributions to the packaging source code so review is easy.

The recommended first step in contributing to a package is to use the built-in "Fork" feature on Salsa. This serves two purposes. Primarily it allows any contributor to publish their git branches and submit them as Merge Requests. Additionally, the mere existence of a list of "Forks" enables contributors to discover each other, and in rare cases when the original package is not accepting improvements, collaboration could arise among the contributors and potentially lead to permanent forks in the general meaning. Forking is a fundamental part of the dynamics in open source that helps drive quality and agreement. The ability to fork ultimately serves as the last line of defense of users' rights. Git supports this by making both temporary and permanent forks easy to create and maintain.

Even small and simple packages should be in on Salsa to welcome collaboration. Source code management is a key aspect in practical collaboration among software developers, and not using git would impose a clear barrier for most potential contributors.

Refrain from non-maintainer uploads (NMU) when possible. NMUs by their nature bypass version control, code reviews, CI testing and all collaboration described in this DEP-18. NMUs should be resorted to only when there is no other reasonable way do for example do a Debian-wide code change. If an NMU does happen, maintainers using git-buildpackage can use the command gbp import-dsc --verbose apt:<package>/sid to automate importing the uploaded changes into version control.

2. Use Merge Requests to Show Your Work and to Get Reviews

Debian packaging work should be reasonably transparent and public to allow contributors to participate. A maintainer should push their pending changes to Salsa at regular intervals, so that a potential contributor can discover if a particular change has already been made, or bug fixed in version control, and thus avoid duplicate work.

Debian maintainers should make reasonable efforts to publish planned changes as Merge Requests on Salsa, and solicit feedback and reviews. While pushing changes directly on the main git branch is the fastest workflow, second only to uploading all changes directly to Debian repositories, it is not an inclusive way to develop software. Even packages that are maintained by a single maintainer should at least occasionally publish Merge Requests to allow for new contributors to step up and participate.

Having multiple people collaborate on a package is likely to ensure the technical decisions are aligned with the broader user base. Additionally, having more people involved helps ensure continuity by having more helping hands available and decrease the burden on a few people who risk being overworked. The quality may also improve following Linus' law "Given enough eyeballs all bugs are shallow".

Collaboration cannot be forced. If a Merge Request does not get any reviews, the original author may self-review them. Reviewing one's own work a week later is usually enough to qualify as a "fresh set of eyes".

For work that is under a security embargo, the maintainer may use their judgment on when, and to whom, share the work. The maintainer may either not publish on Salsa, or publish only in a private repository specifically intended for security embargoed review and testing.

Being open for contributions does not mean that all contributions must be accepted. Each maintainer will choose how high to hold the quality bar, and how much time to spend on reviews. Having the Merge Request feature enabled is however vital for other people to be able to submit contributions, learn what submissions exist from other users, to be able to discuss and review each other's submissions. It also creates visible, browsable history of patch revisions and allows cross-referencing between different merge requests. In some cases it will be valuable that collaborators can easily pull Merge Request submissions into their own forks, in order to exercise their right to fork efficiently.

Collaborators submitting code changes should be encouraged to also contribute reviews of other collaborator's submissions. While the decision to accept a contribution resides with specific maintainers, the ability to review and give feedback on any submission is held by anyone with a Salsa account.

3. Run Salsa CI Before Upload

To ensure that easily testable regressions don't slip into a package, the Debian-specific Salsa CI should be run at least once before the upload to Debian archives. Even though the Debian QA systems do prevent clearly faulty packages from migrating from Debian unstable to testing, a severely broken package may cause havoc merely by existing in Debian unstable. For example, if a key package is broken and fails to install, all development and testing work on packages that depend on it may grind to a halt as all of them become uninstallable.

The maintainer should try to fix all errors detected by the CI system. If the CI system itself is broken, collaboration with the Salsa CI team is encouraged. Depending on the situation, it may also be a reasonable choice to disable some CI jobs. For example, one test could be disabled while pending larger changes to be implemented to fix a complex issue, while all other tests continue to run validate that no other issues arise.

FAQ

Q: Why encourage use of Salsa?

A: At the time of writing, Salsa is the source code hosting platform of Debian. We encourage everyone to assist the Salsa Admin team if they need help, or to contribute directly to upstream GitLab to improve the software itself. Choosing a new source code hosting platform is not in the scope of this proposal. We also encourage everyone to contribute to other Debian infrastructure to make e.g. tracker.debian.org and bugs.debian.org more delightful and efficient to use.

Q: Why not use git.debian.org, Alioth or GNU Quilt?

Salsa is the successor to git.debian.org and Alioth, which have been shut down. GNU Quilt is still widely used, but the git-buildpackage patch-queue feature is superior, does not require contributors to configure per-project Quilt settings nor does it generate any .pc directories.

Due to Debian having 30 years of history, there is plenty of outdated documentation. Active Debian maintainers know which tools to avoid, but explicitly mentioning what not to use anymore is a service to all occasional contributors. Most contributors want to focus their time on actual Debian packaging work and are less keen to learn about various optional packaging related techniques. This DEP-18 plays a role in helping everyone save time on workflow related issues so more time can be spent on actual package maintenance.

Q: How does this relate to dgit?

A: Dgit is a bidirectional gateway between the Debian archive and git. Anyone can use it to view to packages in the Debian archives as if each package was a git repositories, showing every uploaded revision as a git commit. Debian maintainers can use to dgit to upload to the archives. For packages using dgit to upload, the dgit view will also show development commits. It does not include any system to conduct code reviews or record approvals, or to run CI, which this DEP-18 is about. Dgit supports uploading packages from git repositories that are hosted on salsa.debian.org and using git-buildpackage for package development and collaboration. Usage of dgit together with git-buildpackage is described in the man page dgit-maint-gbp(7).

Q: Why encourage use of git-buildpackage?

A: While there are some alternative git packaging workflows, git-buildpackage is currently the most feature complete option, and the only option that supports how all the various upstreams release their software. Even those who prefer dgit for uploading into the Debian archives are likely to use git-buildpackage when interacting with Salsa. Git-buildpackage has been around since 2006, and it is well tested and familiar to most maintainers already. This DEP-18 aims to standardize existing workflows and not invent new ones.

Q: Where can examples of packages following DEP-18 be found?

A: The package and repository of Entr manifests all principles of DEP-18, using Salsa for hosting and git-buildpackage with gbp.conf for automatic settings, and a README.source.md for additional documentation. It also has a track record of using Merge Requests, although only a brief history as the package is small and changes infrequent.

Q: Should all packages be team maintained?

A: This proposal asks maintainers to be more receptive to contributions, but does not propose any changes to who is the decision maker regarding what contributions are accepted. This proposal aims first and foremost set the stage for easier collaboration using Salsa.

Beyond this DEP-18, all maintainers are naturally encouraged to further facilitate collaboration in any way they like, such as forming packaging teams, enforcing use of automatic testing and minimum review rules inside the teams and so forth. Making collaboration easier and more welcoming is likely to attract more contributors to Debian, and make a future where all packages have multiple maintainers more likely. There are also arguments in favor of strong ownership of packages.