Guix — Patch Checklists
Introduction
Based on the Contributing section of the Guix manual and issue 66801, we have summarized rules that must be applied and added some implicit ones below to maximize the chances of a contribution to be merged into Guix while minimizing the mental burden of applying them. This content is intended to be used as pre-flight checklists are.
One patch & one package
| Rule | Source |
|---|---|
| In Emacs, use guix-devel-mode. | Link |
| Use two spaces after sentence ending periods. | Link |
| Use Origin Snippets to remove unwanted files or to apply simple substitutions. | Link |
| arguments, build-system, inputs. | |
./pre-inst-env guix build pkg |
|
If #:tests? #f, then add a comment. If tests are missing, then ; no tests is enough. |
|
| Synopses must start with a capital letter and must not end with a period. | Link |
| Synopses should look like “Manipulate nucleotide sequence alignments”. | Link |
| A description should be at least one full sentence. | Link |
| Commit logs use the ChangeLog format. | Link |
git send-email --annotate --subject-prefix='PATCH' -1 |
Link |
git send-email --annotate -vREVISION --to=ISSUE_NUMBER@debbugs.gnu.org -1 |
Link |
Patch series
| Rule | Source |
|---|---|
| Send a “cover letter” to guix-patches@gnu.org. | Link |
| Agree with the reviewer on the cover letter. | |
| In Emacs, use guix-devel-mode. | Link |
| Use two spaces after sentence ending periods. | Link |
| Don’t mix “styling” changes and other changes. | Link |
| Carry over all other relevant copyright headers. | Link |
| Express yourself in terms of the least verbose primitives. | |
| Use two spaces after sentence ending periods. | Link |
| Use (ice-9 match) rather than car, cdr, etc. | Link |
| Top-level procedures carry a docstring. | Link |
| Use match-record from (guix records) to match records. | Link |
| Avoid using lists to model objects, prefer e.g. define-record-type*. | Link |
| Procedures should not have more than four positional parameters. | Link |
| Use keyword parameters for procedures that take more than four parameters. | Link |
| (guix build …) modules must not refer to (gnu …) or (guix …) modules. | Link |
| Commit logs use the ChangeLog format. | Link |
| Each package should only require the previous ones for building. | |
Format patches with --reroll-count="<n>". |
|
| If a patch is sent again, increase the the reroll count. | |
Format patches with --subject-prefix="PATCH" (check the doc for details). |
|
Send patch with --to="<reviewer email>". |
|
Send patch with --cc="<ISSUE_NUMBER>@debbugs.gnu.org". |
|
Send patch with --suppress-cc=author unless emailing the author is needed. |
|
| Send patches one by one unless the reviewer advises otherwise. |
Conclusion
Based on our experiences contributing patches to Guix, we have compiled this document to consolidate knowledge on the subject as necessary. It is presented in the form of checklists to be applied before submitting patches. It is our hope that these checklists will help streamline the development process for all stakeholders. We welcome any corrections or improvements you may have.