qubes-doc/developer/general/package-contributions.md

lang	layout	permalink	ref	title
en	doc	/doc/package-contributions/	29	Package Contributions

Package Contributions

This page is for developers who wish to contribute packages. If you want to install contributed packages, please see installing contributed packages.

We're very grateful to the talented and hard-working community members who contribute software packages to Qubes OS. This page explains the inclusion criteria and procedures for such packages, as well as the roles and responsibilities of those involved.

Inclusion Criteria

In order to be accepted, packages must:

• In no way weaken the security of Qubes OS.
• Be published under an open-source license (read about the Qubes OS License).
• Follow our coding guidelines.
• Be thoroughly tested.
• Have a clearly-defined use case for Qubes users.
• Not be unduly burdensome to review.

(Please note that we always reserve the right to add criteria to this list.)

Contribution Procedure

Before you start putting serious work into a package, we recommend that you discuss your idea with the Qubes developers and the broader community on the qubes-devel mailing list. Once you have a package that's ready to become part of Qubes OS, please follow this procedure:

1. Ensure that your package satisfies the Inclusion Criteria.
2. If your code isn't already on GitHub, create a GitHub repo that contains your code. You can have a look to an example package called qubes-skeleton.
3. If you haven't already, sign your code.
4. Create an issue in qubes-issues with the title [Contribution] your-package-name. Include a link to your repo, a brief description of your package, and a brief explanation of why you think it should be included in Qubes. Please note that the Qubes core developers are very busy. If they are under heavy load when you submit your contribution, it may be a very long time before they have time to review your package. If this happens, please do not be discouraged. If you think they may have forgotten about your pending contribution, you may "bump" your request by commenting on your issue, but please do this very sparingly (i.e., no more than once a month). We appreciate your understanding!
5. You may be asked followup questions. If we decide to accept your contribution, you will be invited to join the QubesOS-contrib organization on GitHub as public recognition of your contribution (but without push access; see Review Procedure), and QubesOS-contrib will fork your repo. If we decide not to accept your contribution, we will state the reason and close the issue.

Update Procedure

Anyone can provide an update (patch) to a contributed package, not just the person who contributed that package! The update procedure is the same for everyone, including the original package contributor.

If you would like to update an already-contributed package (specifically, a fork owned by QubesOS-contrib), please submit a signed, fast-forwardable pull request to that repo with your changes. Please note that your pull request must be both signed and fast-forwardable, or else it will be closed without further review. One or more reviewers may post comments on your pull request. Please be prepared to read and respond to these comments.

Review Procedure

This review procedure covers both original package contributions (see Contribution Procedure) and all subsequent updates to those packages, including updates from the original package contributor (see Update Procedure). All changes will be reviewed by a Qubes Core Reviewer (QCR) and the Package Maintainer (PM). In all cases, the QCR will be a core Qubes developer. In some cases, the QCR and the PM will be the same person. For example, if someone contributes a package, then disappears, and no suitable replacement has been found, then it is likely that a core Qubes developer will play both the QCR and PM roles for that package, at least until another suitable candidate volunteers to become the PM for that package.

The review procedure is as follows:

1. Someone, S, wishes to make a change to a package, P.
2. S submits a fast-forwardable pull request against the fork of P's repo owned by QubesOS-contrib.
3. The PM reviews the pull request. If the the pull request passes the PM's review, the PM adds a signed comment on the pull request stating that it has passed review. (In cases in which S = PM, the PM can simply add a signed tag to the HEAD commit prior to submitting the pull request.) If the pull request does not pass the PM's review, the PM leaves a comment on the pull request explaining why not.
4. The QCR reviews the pull request. If the pull request passes the QCR's review, the QCR pushes a signed tag to the HEAD commit stating that it has passed review and fast-forward merges the pull request. If the pull request does not pass the QCR's review, the QCR leaves a comment on the pull request explaining why not, and the QCR may decide to close the pull request.

In all the cases, the first condition to be validated by the QCR's review is to ensure that the contribution will not hijack any core packages of QubesOS and of course, none of the QubesOS-contrib packages too. More precisely, particular attention to the whole build pipeline will be made with a specific review of:

• Package dependencies,
• Build scripts (including downloaded ones),
• All downloaded components should be verified against static hash,
• RPM/DEB installation scripts (e.g. looking at constraints who would hijack other packages),
• Makefiles,
• Package build reproducible

and any steps which would result in partial/total compromise of legitimate components. For this part, you can have a look to an example package called qubes-skeleton.

Package Maintainers

If you contribute a package, we assume that you will be the maintainer of that package, unless you tell us otherwise. As the maintainer of the package, it is your privilege and responsibility to:

• Review each pull request made against the package.
• Decide when the package has reached a new version, and notify the Qubes core developers when this occurs.

If you do not wish to be the maintainer of your package, please let us know. If you do not act on your maintainer duties for a given package for an extended period of time and after at least one reminder, we will assume that you no longer wish to be the maintainer for that package.