| 1 | @node Contributing |
| 2 | @chapter Contributing |
| 3 | |
| 4 | This project is a cooperative effort, and we need your help to make it |
| 5 | grow! Please get in touch with us on @email{guix-devel@@gnu.org} and |
| 6 | @code{#guix} on the Libera Chat IRC network. We welcome ideas, bug |
| 7 | reports, patches, and anything that may be helpful to the project. We |
| 8 | particularly welcome help on packaging (@pxref{Packaging Guidelines}). |
| 9 | |
| 10 | @cindex code of conduct, of contributors |
| 11 | @cindex contributor covenant |
| 12 | We want to provide a warm, friendly, and harassment-free environment, so |
| 13 | that anyone can contribute to the best of their abilities. To this end |
| 14 | our project uses a ``Contributor Covenant'', which was adapted from |
| 15 | @url{https://contributor-covenant.org/}. You can find a local version in |
| 16 | the @file{CODE-OF-CONDUCT} file in the source tree. |
| 17 | |
| 18 | Contributors are not required to use their legal name in patches and |
| 19 | on-line communication; they can use any name or pseudonym of their |
| 20 | choice. |
| 21 | |
| 22 | @menu |
| 23 | * Requirements:: Software needed to build and run Guix. |
| 24 | * Building from Git:: The latest and greatest. |
| 25 | * Running the Test Suite:: Testing Guix. |
| 26 | * Running Guix Before It Is Installed:: Hacker tricks. |
| 27 | * The Perfect Setup:: The right tools. |
| 28 | * Source Tree Structure:: Source code guided tour. |
| 29 | * Packaging Guidelines:: Growing the distribution. |
| 30 | * Coding Style:: Hygiene of the contributor. |
| 31 | * Submitting Patches:: Share your work. |
| 32 | * Tracking Bugs and Changes:: Keeping it all organized. |
| 33 | * Teams:: Coordinating efforts. |
| 34 | * Making Decisions:: Collectively choosing the way forward. |
| 35 | * Commit Access:: Pushing to the official repository. |
| 36 | * Reviewing the Work of Others:: Some guidelines for sharing reviews. |
| 37 | * Updating the Guix Package:: Updating the Guix package definition. |
| 38 | * Deprecation Policy:: Commitments and tools for deprecation. |
| 39 | * Writing Documentation:: Improving documentation in GNU Guix. |
| 40 | * Translating Guix:: Make Guix speak your native language. |
| 41 | * Contributing to Guix's Infrastructure:: Make Guix ecosystem work better. |
| 42 | @end menu |
| 43 | |
| 44 | @node Requirements |
| 45 | @section Requirements |
| 46 | |
| 47 | You can easily hack on Guix itself using Guix and Git, which we use for |
| 48 | version control (@pxref{Building from Git}). |
| 49 | |
| 50 | But when packaging Guix for foreign distros or when bootstrapping on |
| 51 | systems without Guix, and if you decide to not just trust and install |
| 52 | our readily made binary (@pxref{Binary Installation}), you can download |
| 53 | a release version of our reproducible source tarball and read on. |
| 54 | |
| 55 | This section lists requirements when building Guix from source. The |
| 56 | build procedure for Guix is the same as for other GNU software, and is |
| 57 | not covered here. Please see the files @file{README} and @file{INSTALL} |
| 58 | in the Guix source tree for additional details. |
| 59 | |
| 60 | @cindex official website |
| 61 | GNU Guix is available for download from its website at |
| 62 | @url{https://guix.gnu.org}. |
| 63 | |
| 64 | GNU Guix depends on the following packages: |
| 65 | |
| 66 | @itemize |
| 67 | @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x, |
| 68 | version 3.0.9 or later; |
| 69 | @item @url{https://codeberg.org/guile-gcrypt/guile-gcrypt, Guile-Gcrypt}, version |
| 70 | 0.1.0 or later; |
| 71 | @item |
| 72 | @uref{https://codeberg.org/guile-gnutls/guile-gnutls, Guile-GnuTLS} (@pxref{Guile |
| 73 | Preparations, how to install the GnuTLS bindings for Guile,, |
| 74 | gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to |
| 75 | @uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS |
| 76 | until version 3.7.8 included.}; |
| 77 | @item |
| 78 | @uref{https://codeberg.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0 |
| 79 | or later; |
| 80 | @item @uref{https://codeberg.org/guile-compression/guile-zlib, Guile-zlib}, |
| 81 | version 0.1.0 or later; |
| 82 | @item @uref{https://codeberg.org/guile-compression/guile-lzlib, Guile-lzlib}; |
| 83 | @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi}; |
| 84 | @item |
| 85 | @uref{https://codeberg.org/guile-git/guile-git, Guile-Git}, version 0.10.0 |
| 86 | or later; |
| 87 | @item @uref{https://git-scm.com, Git} (yes, both!); |
| 88 | @item @uref{https://github.com/aconchillo/guile-json, Guile-JSON} |
| 89 | 4.3.0 or later; |
| 90 | @item @url{https://www.gnu.org/software/make/, GNU Make}. |
| 91 | @end itemize |
| 92 | |
| 93 | The following dependencies are optional: |
| 94 | |
| 95 | @itemize |
| 96 | @item |
| 97 | @c Note: We need at least 0.13.0 for #:nodelay. |
| 98 | Support for build offloading (@pxref{Daemon Offload Setup}) and |
| 99 | @command{guix copy} (@pxref{Invoking guix copy}) depends on |
| 100 | @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, |
| 101 | version 0.13.0 or later. |
| 102 | |
| 103 | @item |
| 104 | @uref{https://codeberg.org/guile-compression/guile-zstd, Guile-zstd}, for zstd |
| 105 | compression and decompression in @command{guix publish} and for |
| 106 | substitutes (@pxref{Invoking guix publish}). |
| 107 | |
| 108 | @item |
| 109 | @uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for |
| 110 | the @code{crate} importer (@pxref{Invoking guix import}). |
| 111 | |
| 112 | @item |
| 113 | @uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for |
| 114 | the @code{go} importer (@pxref{Invoking guix import}) and for some of |
| 115 | the ``updaters'' (@pxref{Invoking guix refresh}). |
| 116 | |
| 117 | @item |
| 118 | When @url{http://www.bzip.org, libbz2} is available, |
| 119 | @command{guix-daemon} can use it to compress build logs. |
| 120 | @end itemize |
| 121 | |
| 122 | Unless @option{--disable-daemon} was passed to @command{configure}, the |
| 123 | following packages are also needed: |
| 124 | |
| 125 | @itemize |
| 126 | @item @url{https://gnupg.org/, GNU libgcrypt}; |
| 127 | @item @url{https://sqlite.org, SQLite 3}; |
| 128 | @item @url{https://gcc.gnu.org, GCC's g++}, with support for the |
| 129 | C++11 standard. |
| 130 | @end itemize |
| 131 | |
| 132 | @node Building from Git |
| 133 | @section Building from Git |
| 134 | |
| 135 | If you want to hack Guix itself, it is recommended to use the latest |
| 136 | version from the Git repository@footnote{ |
| 137 | Guix uses @code{master} as the default branch name. A proposal in 2025 to |
| 138 | change the default branch name to @code{main} did not reach consensus. |
| 139 | See @uref{https://codeberg.org/guix/guix-consensus-documents/src/branch/main/003-rename-default-branch.md, |
| 140 | Guix Consensus Document 003}.}: |
| 141 | |
| 142 | @example |
| 143 | git clone https://git.guix.gnu.org/guix.git |
| 144 | cd guix |
| 145 | @end example |
| 146 | |
| 147 | @cindex authentication, of a Guix checkout |
| 148 | How do you ensure that you obtained a genuine copy of the repository? |
| 149 | To do that, run @command{guix git authenticate}, passing it the commit |
| 150 | and OpenPGP fingerprint of the @dfn{channel introduction} |
| 151 | (@pxref{Invoking guix git authenticate}): |
| 152 | |
| 153 | @c The commit and fingerprint below must match those of the channel |
| 154 | @c introduction in '%default-channels'. |
| 155 | @example |
| 156 | guix git authenticate -k origin/keyring \ |
| 157 | 9edb3f66fd807b096b48283debdcddccfea34bad \ |
| 158 | "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" |
| 159 | @end example |
| 160 | |
| 161 | @noindent |
| 162 | This command completes with exit code zero on success; it prints an |
| 163 | error message and exits with a non-zero code otherwise. |
| 164 | |
| 165 | As you can see, there is a chicken-and-egg problem: you first need to |
| 166 | have Guix installed. Typically you would install Guix System |
| 167 | (@pxref{System Installation}) or Guix on top of another distro |
| 168 | (@pxref{Binary Installation}); in either case, you would verify the |
| 169 | OpenPGP signature on the installation medium. This ``bootstraps'' the |
| 170 | trust chain. |
| 171 | |
| 172 | The easiest way to set up a development environment for Guix is, of |
| 173 | course, by using Guix! The following command starts a new shell where |
| 174 | all the dependencies and appropriate environment variables are set up to |
| 175 | hack on Guix: |
| 176 | |
| 177 | @example |
| 178 | guix shell -D guix --pure |
| 179 | @end example |
| 180 | |
| 181 | or even, from within a Git worktree for Guix: |
| 182 | |
| 183 | @example |
| 184 | echo $(pwd) >> ~/.config/guix/shell-authorized-directories |
| 185 | guix shell --pure |
| 186 | @end example |
| 187 | |
| 188 | If you are unable to use Guix when building Guix from a checkout, the |
| 189 | following are the required packages in addition to those mentioned in the |
| 190 | installation instructions (@pxref{Requirements}). |
| 191 | |
| 192 | @itemize |
| 193 | @item @url{https://gnu.org/software/autoconf/, GNU Autoconf}; |
| 194 | @item @url{https://gnu.org/software/automake/, GNU Automake}; |
| 195 | @item @url{https://gnu.org/software/gettext/, GNU Gettext}; |
| 196 | @item @url{https://gnu.org/software/texinfo/, GNU Texinfo}; |
| 197 | @item @url{https://www.graphviz.org/, Graphviz}; |
| 198 | @item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}. |
| 199 | @end itemize |
| 200 | |
| 201 | On Guix, other development tools, like @code{strace}, can be included by |
| 202 | giving them as extra arguments to @command{guix shell}: |
| 203 | |
| 204 | @example |
| 205 | guix shell --pure -D guix strace |
| 206 | @end example |
| 207 | |
| 208 | From there you can generate the build system infrastructure |
| 209 | using Autoconf and Automake: |
| 210 | |
| 211 | @example |
| 212 | ./bootstrap |
| 213 | @end example |
| 214 | |
| 215 | If you get an error like this one: |
| 216 | |
| 217 | @example |
| 218 | configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES |
| 219 | @end example |
| 220 | |
| 221 | @noindent |
| 222 | it probably means that Autoconf couldn’t find @file{pkg.m4}, which is |
| 223 | provided by pkg-config. Make sure that @file{pkg.m4} is available. The |
| 224 | same holds for the @file{guile.m4} set of macros provided by Guile. For |
| 225 | instance, if you installed Automake in @file{/usr/local}, it wouldn’t |
| 226 | look for @file{.m4} files in @file{/usr/share}. In that case, you have |
| 227 | to invoke the following command: |
| 228 | |
| 229 | @example |
| 230 | export ACLOCAL_PATH=/usr/share/aclocal |
| 231 | @end example |
| 232 | |
| 233 | @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for |
| 234 | more information. |
| 235 | |
| 236 | @cindex state directory |
| 237 | @cindex localstatedir |
| 238 | @cindex system configuration directory |
| 239 | @cindex sysconfdir |
| 240 | Then, run: |
| 241 | |
| 242 | @example |
| 243 | ./configure |
| 244 | @end example |
| 245 | |
| 246 | @noindent |
| 247 | Optionally, @code{--localstatedir} and @code{--sysconfdir} can also be |
| 248 | provided as arguments. By default, @code{localstatedir} is @file{/var} |
| 249 | (@pxref{The Store}, for information about this) and @code{sysconfdir} is |
| 250 | @file{/etc}. Note that you will probably not run @command{make install} |
| 251 | at the end (you don't have to) but it's still important to pass the |
| 252 | right @code{localstatedir} and @code{sysconfdir} values, which get |
| 253 | recorded in the @code{(guix config)} Guile module. |
| 254 | |
| 255 | Finally, you can build Guix and, if you feel so inclined, run the tests |
| 256 | (depending on how you setup your environment, some tests might fail, |
| 257 | @pxref{Running the Test Suite}): |
| 258 | |
| 259 | @example |
| 260 | make |
| 261 | make check |
| 262 | @end example |
| 263 | |
| 264 | From there on, you can authenticate all the commits included in your |
| 265 | checkout by running: |
| 266 | |
| 267 | @example |
| 268 | guix git authenticate -k origin/keyring \ |
| 269 | 9edb3f66fd807b096b48283debdcddccfea34bad \ |
| 270 | "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" |
| 271 | @end example |
| 272 | |
| 273 | The first run takes a couple of minutes, but subsequent runs are faster. |
| 274 | On subsequent runs, you can run the command without any arguments since |
| 275 | the @dfn{introduction} (the commit ID and OpenPGP fingerprints above) |
| 276 | will have been recorded@footnote{This requires a recent version of Guix, |
| 277 | from May 2024 or more recent.}: |
| 278 | |
| 279 | @example |
| 280 | guix git authenticate |
| 281 | @end example |
| 282 | |
| 283 | When your configuration for your local Git repository doesn't match |
| 284 | the default one, you can provide the reference for the @code{keyring} |
| 285 | branch @i{via} the @option{-k} option. The following |
| 286 | example assumes that you have a Git remote called @samp{myremote} |
| 287 | pointing to the official repository: |
| 288 | |
| 289 | @example |
| 290 | guix git authenticate \ |
| 291 | -k myremote/keyring \ |
| 292 | 9edb3f66fd807b096b48283debdcddccfea34bad \ |
| 293 | "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" |
| 294 | @end example |
| 295 | |
| 296 | @xref{Invoking guix git authenticate}, for more information on this |
| 297 | command. |
| 298 | |
| 299 | @quotation Note |
| 300 | By default, hooks are installed such that @command{guix git |
| 301 | authenticate} is invoked anytime you run @command{git pull} or |
| 302 | @command{git push}. |
| 303 | @end quotation |
| 304 | |
| 305 | After updating the repository, @command{make} might fail with an error |
| 306 | similar to the following example: |
| 307 | |
| 308 | @example |
| 309 | error: failed to load 'gnu/packages/linux.scm': |
| 310 | ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed |
| 311 | @end example |
| 312 | |
| 313 | This means that one of the record types that Guix defines (in this |
| 314 | example, the @code{origin} record) has changed, and all of guix needs |
| 315 | to be recompiled to take that change into account. To do so, run |
| 316 | @command{make clean-go} followed by @command{make}. |
| 317 | |
| 318 | Should @command{make} fail with an Automake error message after |
| 319 | updating, you need to repeat the steps outlined in this section, |
| 320 | commencing with @command{./bootstrap}. |
| 321 | |
| 322 | @node Running the Test Suite |
| 323 | @section Running the Test Suite |
| 324 | |
| 325 | @cindex test suite |
| 326 | After a successful @command{configure} and @code{make} run, it is a good |
| 327 | idea to run the test suite. It can help catch issues with the setup or |
| 328 | environment, or bugs in Guix itself---and really, reporting test |
| 329 | failures is a good way to help improve the software. To run the test |
| 330 | suite, type: |
| 331 | |
| 332 | @example |
| 333 | make check |
| 334 | @end example |
| 335 | |
| 336 | Some tests might fail or be skipped, depending on your environment. |
| 337 | For example, many tests require Internet access to download test |
| 338 | binaries into the temporary store used for testing. |
| 339 | |
| 340 | Assuming you set up your environment with @command{guix shell}, |
| 341 | this is what you can expect: |
| 342 | |
| 343 | @table @option |
| 344 | @item --pure |
| 345 | all tests should either pass or be skipped. This will also |
| 346 | set up the test store; |
| 347 | @item -CPWN |
| 348 | all tests should either pass or be skipped and this should |
| 349 | also set up the test store@footnote{At the time of writing, June 2026, |
| 350 | some tests might fail in a @option{-CPWN} shell; those are |
| 351 | @url{https://codeberg.org/guix/guix/issues/9381, bugs}.}; |
| 352 | @item -CPW |
| 353 | all network tests should automatically be skipped, but tests |
| 354 | that require the test store are run, so those will fail unless the test store |
| 355 | has been set up during an earlier test run with network access. |
| 356 | @end table |
| 357 | |
| 358 | @quotation Note |
| 359 | Some tests are skipped for other reasons, for example because they are |
| 360 | only applicable for a specific system. |
| 361 | @end quotation |
| 362 | |
| 363 | Test cases can run in parallel: you can use the @code{-j} option of |
| 364 | GNU@tie{}make to speed things up. The first run may take a few minutes |
| 365 | on a recent machine; subsequent runs will be faster because the store |
| 366 | that is created for test purposes will already have various things in |
| 367 | cache. |
| 368 | |
| 369 | It is also possible to run a subset of the tests by defining the |
| 370 | @code{TESTS} makefile variable as in this example: |
| 371 | |
| 372 | @example |
| 373 | make check TESTS="tests/store.scm tests/cpio.scm" |
| 374 | @end example |
| 375 | |
| 376 | By default, tests results are displayed at a file level. In order to |
| 377 | see the details of every individual test cases, it is possible to define |
| 378 | the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example: |
| 379 | |
| 380 | @example |
| 381 | make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" |
| 382 | @end example |
| 383 | |
| 384 | The underlying SRFI 64 custom Automake test driver used for the 'check' |
| 385 | test suite (located at @file{build-aux/test-driver.scm}) also allows |
| 386 | selecting which test cases to run at a finer level, via its |
| 387 | @option{--select} and @option{--exclude} options. Here's an example, to |
| 388 | run all the test cases from the @file{tests/packages.scm} test file |
| 389 | whose names start with ``transaction-upgrade-entry'': |
| 390 | |
| 391 | @example |
| 392 | export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry" |
| 393 | make check TESTS="tests/packages.scm" |
| 394 | @end example |
| 395 | |
| 396 | Those wishing to inspect the results of failed tests directly from the |
| 397 | command line can add the @option{--errors-only=yes} option to the |
| 398 | @code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE} |
| 399 | Automake makefile variable, as in: |
| 400 | |
| 401 | @example |
| 402 | make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1 |
| 403 | @end example |
| 404 | |
| 405 | The @option{--show-duration=yes} option can be used to print the |
| 406 | duration of the individual test cases, when used in combination with |
| 407 | @option{--brief=no}: |
| 408 | |
| 409 | @example |
| 410 | make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes" |
| 411 | @end example |
| 412 | |
| 413 | @xref{Parallel Test Harness,,,automake,GNU Automake} for more |
| 414 | information about the Automake Parallel Test Harness. |
| 415 | |
| 416 | Upon failure, please see if there already exists an issue which |
| 417 | describes your problem on @uref{https://codeberg.org/guix/guix/issues, |
| 418 | Codeberg}, else create a new one and attach the @file{test-suite.log} |
| 419 | file. Please specify the Guix version being used as well as version |
| 420 | numbers of the dependencies (@pxref{Requirements}) in your message by |
| 421 | running @code{./pre-inst-env guix describe}. |
| 422 | |
| 423 | Guix also comes with a whole-system test suite that tests complete |
| 424 | Guix System instances. It can only run on systems where |
| 425 | Guix is already installed, using: |
| 426 | |
| 427 | @example |
| 428 | make check-system |
| 429 | @end example |
| 430 | |
| 431 | @noindent |
| 432 | or, again, by defining @code{TESTS} to select a subset of tests to run: |
| 433 | |
| 434 | @example |
| 435 | make check-system TESTS="basic mcron" |
| 436 | @end example |
| 437 | |
| 438 | These system tests are defined in the @code{(gnu tests @dots{})} |
| 439 | modules. They work by running the operating systems under test with |
| 440 | lightweight instrumentation in a virtual machine (VM). They can be |
| 441 | computationally intensive or rather cheap, depending on whether |
| 442 | substitutes are available for their dependencies (@pxref{Substitutes}). |
| 443 | Some of them require a lot of storage space to hold VM images. |
| 444 | |
| 445 | If you encounter an error like: |
| 446 | |
| 447 | @example |
| 448 | Compiling Scheme modules... |
| 449 | ice-9/eval.scm:142:16: In procedure compile-top-call: |
| 450 | error: all-system-tests: unbound variable |
| 451 | hint: Did you forget `(use-modules (gnu tests))'? |
| 452 | @end example |
| 453 | |
| 454 | @noindent |
| 455 | there may be inconsistencies in the work tree from previous builds. To |
| 456 | resolve this, try running @command{make clean-go} followed by |
| 457 | @command{make}. |
| 458 | |
| 459 | Again in case of test failures, open an issue on |
| 460 | @uref{https://codeberg.org/guix/guix/issues, Codeberg} with all the |
| 461 | details. |
| 462 | |
| 463 | @node Running Guix Before It Is Installed |
| 464 | @section Running Guix Before It Is Installed |
| 465 | |
| 466 | In order to keep a sane working environment, you will find it useful to |
| 467 | test the changes made in your local source tree checkout without |
| 468 | actually installing them. So that you can distinguish between your |
| 469 | ``end-user'' hat and your ``motley'' costume. |
| 470 | |
| 471 | To that end, all the command-line tools can be used even if you have not |
| 472 | run @code{make install}. To do that, you first need to have an |
| 473 | environment with all the dependencies available (@pxref{Building from |
| 474 | Git}), and then simply prefix each command with @command{./pre-inst-env} |
| 475 | (the @file{pre-inst-env} script lives in the top build tree of Guix; |
| 476 | @pxref{Building from Git} to generate it). As an example, here is how you |
| 477 | would build the @code{hello} package as defined in your working tree (this |
| 478 | assumes @command{guix-daemon} is already running on your system; it's OK if |
| 479 | it's a different version): |
| 480 | |
| 481 | @example |
| 482 | $ ./pre-inst-env guix build hello |
| 483 | @end example |
| 484 | |
| 485 | @noindent |
| 486 | Similarly, an example for a Guile session using the Guix modules: |
| 487 | |
| 488 | @example |
| 489 | $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' |
| 490 | |
| 491 | ;;; ("x86_64-linux") |
| 492 | @end example |
| 493 | |
| 494 | @noindent |
| 495 | @cindex REPL |
| 496 | @cindex read-eval-print loop |
| 497 | @dots{} and for a REPL (@pxref{Using Guix Interactively}): |
| 498 | |
| 499 | @example |
| 500 | $ ./pre-inst-env guile |
| 501 | scheme@@(guile-user)> ,use(guix) |
| 502 | scheme@@(guile-user)> ,use(gnu) |
| 503 | scheme@@(guile-user)> (define snakes |
| 504 | (fold-packages |
| 505 | (lambda (package lst) |
| 506 | (if (string-prefix? "python" |
| 507 | (package-name package)) |
| 508 | (cons package lst) |
| 509 | lst)) |
| 510 | '())) |
| 511 | scheme@@(guile-user)> (length snakes) |
| 512 | $1 = 361 |
| 513 | @end example |
| 514 | |
| 515 | If you are hacking on the daemon and its supporting code or if |
| 516 | @command{guix-daemon} is not already running on your system, you can |
| 517 | launch it straight from the build tree@footnote{The @option{-E} flag to |
| 518 | @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set |
| 519 | such that @command{guix-daemon} and the tools it uses can find the Guile |
| 520 | modules they need.}: |
| 521 | |
| 522 | @example |
| 523 | $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild |
| 524 | @end example |
| 525 | |
| 526 | The @command{pre-inst-env} script sets up all the environment variables |
| 527 | necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}. |
| 528 | |
| 529 | Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the |
| 530 | local source tree; it simply updates the @file{~/.config/guix/current} |
| 531 | symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if |
| 532 | you want to upgrade your local source tree. |
| 533 | |
| 534 | Sometimes, especially if you have recently updated your repository, |
| 535 | running @command{./pre-inst-env} will print a message similar to the |
| 536 | following example: |
| 537 | |
| 538 | @example |
| 539 | ;;; note: source file /home/user/projects/guix/guix/progress.scm |
| 540 | ;;; newer than compiled /home/user/projects/guix/guix/progress.go |
| 541 | @end example |
| 542 | |
| 543 | This is only a note and you can safely ignore it. You can get rid of |
| 544 | the message by running @command{make -j4}. Until you do, Guile will run |
| 545 | slightly slower because it will interpret the code instead of using |
| 546 | prepared Guile object (@file{.go}) files. |
| 547 | |
| 548 | You can run @command{make} automatically as you work using |
| 549 | @command{watchexec} from the @code{watchexec} package. For example, |
| 550 | to build again each time you update a package file, run |
| 551 | @samp{watchexec -w gnu/packages -- make -j4}. |
| 552 | |
| 553 | @node The Perfect Setup |
| 554 | @section The Perfect Setup |
| 555 | |
| 556 | @cindex editor setup, for Scheme |
| 557 | @cindex Scheme code editing |
| 558 | All configuration and development in Guix is done in the Scheme |
| 559 | language. Like all languages of the Lisp family, Scheme has a simple |
| 560 | syntax. The perfect setup is one where the editor you choose makes |
| 561 | working with that syntax seamless and pleasant; for that it must |
| 562 | absolutely support a few things for Scheme: |
| 563 | |
| 564 | @itemize |
| 565 | @item |
| 566 | automatic indentation, such that hitting the ``Enter'' key (or |
| 567 | @kbd{RET}) places cursor ``at the right place'' on the next line; |
| 568 | @item |
| 569 | ``parentheses matching'', allowing you to jump from a closing |
| 570 | parenthesis to the corresponding opening parenthesis and vice-versa; |
| 571 | @item |
| 572 | syntax highlighting, so that keywords are visually distinguishable. |
| 573 | @end itemize |
| 574 | |
| 575 | The following optional features can make your life easier: |
| 576 | |
| 577 | @itemize |
| 578 | @item |
| 579 | structural editing of Scheme syntax; |
| 580 | @item |
| 581 | Guile integration so you can easily evaluate code, jump to procedure |
| 582 | definitions, view documentation, and so on. |
| 583 | @end itemize |
| 584 | |
| 585 | The following sections look at editor setups that are known to work |
| 586 | well. Do share your setup for these and other editors for inclusion in |
| 587 | this manual! @xref{Submitting Patches}. |
| 588 | |
| 589 | @menu |
| 590 | * Emacs:: Best-of-breed editor for Scheme code. |
| 591 | * Guile Studio:: First step in your transition to Emacs. |
| 592 | * Vim and NeoVim:: Classical Unix editors. |
| 593 | @end menu |
| 594 | |
| 595 | @node Emacs |
| 596 | @subsection Emacs |
| 597 | |
| 598 | @url{https://www.gnu.org/software/emacs, Emacs} is probably the most |
| 599 | widely used editor in the community; it is also the one that, |
| 600 | historically, has always had excellent support for Lisp languages, being |
| 601 | itself a Lisp implementation! |
| 602 | |
| 603 | @quotation Note |
| 604 | If you are just getting started with Emacs, @pxref{Guile Studio} for a |
| 605 | smooth way to start your transition. |
| 606 | @end quotation |
| 607 | |
| 608 | Just like for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile |
| 609 | Reference Manual}), Emacs works best when empowered by the wonderful |
| 610 | @url{https://nongnu.org/geiser/, Geiser}. To set that up, run: |
| 611 | |
| 612 | @example |
| 613 | guix install emacs guile emacs-geiser emacs-geiser-guile emacs-guix |
| 614 | @end example |
| 615 | |
| 616 | Geiser allows for interactive and incremental development from within |
| 617 | Emacs: code compilation and evaluation from within buffers, access to |
| 618 | on-line documentation (docstrings), context-sensitive completion, |
| 619 | @kbd{M-.} to jump to an object definition, a REPL to try out your code, |
| 620 | and more (@pxref{Introduction,,, geiser, Geiser User Manual}). If you |
| 621 | allow Emacs to load the @file{.dir-locals.el} file at the root of the |
| 622 | project checkout, it will cause Geiser to automatically add the local |
| 623 | Guix sources to the Guile load path. |
| 624 | |
| 625 | To actually edit the code, Emacs already has a neat Scheme mode. But in |
| 626 | addition to that, you must not miss |
| 627 | @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides |
| 628 | facilities to directly operate on the syntax tree, such as raising an |
| 629 | s-expression or wrapping it, swallowing or rejecting the following |
| 630 | s-expression, etc. |
| 631 | |
| 632 | Cherry on the cake: the Emacs-Guix package provides a convenient |
| 633 | interface to many commands---e.g., it lets you browse packages, install |
| 634 | or remove packages, and so on---as well as development helpers that |
| 635 | enhance @code{scheme-mode} and Geiser. @xref{Introduction,,, |
| 636 | emacs-guix, Emacs-Guix Reference Manual}, to make sure you don't miss |
| 637 | out! |
| 638 | |
| 639 | @unnumberedsubsubsec Submitting Pull Requests Following the AGit Workflow |
| 640 | |
| 641 | @cindex AGit workflow, for pull requests (Emacs). |
| 642 | @url{https://codeberg.org/halvin/agitjo, Agitjo} is a helper to ease |
| 643 | AGit workflow based patch submission (@pxref{Submitting Patches}). |
| 644 | Install it with: |
| 645 | |
| 646 | @example |
| 647 | guix install emacs-agitjo |
| 648 | @end example |
| 649 | |
| 650 | Assuming your local checkout is on the branch containing the changes you |
| 651 | would like to submit for inclusion in the @code{master} branch, use |
| 652 | @command{M-x agitjo-push} then: |
| 653 | |
| 654 | @itemize |
| 655 | @item |
| 656 | Set options like the title @option{-t} and the session identifier |
| 657 | @option{-s}. |
| 658 | @item |
| 659 | Invoke one of the push commands to execute a @command{git push} operation. |
| 660 | @end itemize |
| 661 | |
| 662 | When creating a new pull request, a dedicated buffer will open for |
| 663 | drafting a description. The force-push option @option{-f} is enabled to |
| 664 | push changes to the existing pull request. |
| 665 | |
| 666 | @unnumberedsubsubsec Taming Boilerplate with Templates |
| 667 | |
| 668 | @cindex code snippets |
| 669 | @cindex templates |
| 670 | @cindex reducing boilerplate |
| 671 | We also provide templates for common git commit messages and package |
| 672 | definitions in the @file{etc/snippets} directory. These templates can |
| 673 | be used to expand short trigger strings to interactive text snippets. If |
| 674 | you use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you |
| 675 | may want to add the @file{etc/snippets/yas} snippets directory to the |
| 676 | @var{yas-snippet-dirs} variable. If you use |
| 677 | @url{https://github.com/minad/tempel/, Tempel}, you may want to add the |
| 678 | @file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in |
| 679 | Emacs. |
| 680 | |
| 681 | @lisp |
| 682 | ;; @r{Assuming the Guix checkout is in ~/src/guix.} |
| 683 | ;; @r{Yasnippet configuration} |
| 684 | (with-eval-after-load 'yasnippet |
| 685 | (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas")) |
| 686 | ;; @r{Tempel configuration} |
| 687 | (with-eval-after-load 'tempel |
| 688 | ;; Ensure tempel-path is a list -- it may also be a string. |
| 689 | (unless (listp 'tempel-path) |
| 690 | (setq tempel-path (list tempel-path))) |
| 691 | (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*")) |
| 692 | @end lisp |
| 693 | |
| 694 | The commit message snippets depend on @url{https://magit.vc/, Magit} to |
| 695 | display staged files. When editing a commit message type @code{add} |
| 696 | followed by @kbd{TAB} to insert a commit message template for adding a |
| 697 | package; type @code{update} followed by @kbd{TAB} to insert a template |
| 698 | for updating a package; type @code{https} followed by @kbd{TAB} to |
| 699 | insert a template for changing the home page URI of a package to HTTPS. |
| 700 | |
| 701 | The main snippet for @code{scheme-mode} is triggered by typing |
| 702 | @code{package...} followed by @kbd{TAB}. This snippet also inserts the |
| 703 | trigger string @code{origin...}, which can be expanded further. The |
| 704 | @code{origin} snippet in turn may insert other trigger strings ending on |
| 705 | @code{...}, which also can be expanded further. |
| 706 | |
| 707 | @unnumberedsubsubsec Updating Copyright Lines |
| 708 | |
| 709 | @cindex insert or update copyright |
| 710 | @cindex @code{M-x guix-copyright} |
| 711 | @cindex @code{M-x copyright-update} |
| 712 | We additionally provide insertion and automatic update of a copyright in |
| 713 | @file{etc/copyright.el}. You may want to set your full name, mail, and |
| 714 | load a file. |
| 715 | |
| 716 | @lisp |
| 717 | (setq user-full-name "Alice Doe") |
| 718 | (setq user-mail-address "alice@@mail.org") |
| 719 | ;; @r{Assuming the Guix checkout is in ~/src/guix.} |
| 720 | (load-file "~/src/guix/etc/copyright.el") |
| 721 | @end lisp |
| 722 | |
| 723 | To insert a copyright at the current line invoke @code{M-x guix-copyright}. |
| 724 | |
| 725 | To update a copyright you need to specify a @code{copyright-names-regexp}. |
| 726 | |
| 727 | @lisp |
| 728 | (setq copyright-names-regexp |
| 729 | (format "%s <%s>" user-full-name user-mail-address)) |
| 730 | @end lisp |
| 731 | |
| 732 | You can check if your copyright is up to date by evaluating @code{M-x |
| 733 | copyright-update}. If you want to do it automatically after each buffer |
| 734 | save then add @code{(add-hook 'after-save-hook 'copyright-update)} in |
| 735 | Emacs. |
| 736 | |
| 737 | @unnumberedsubsubsec Referencing Bug Reports |
| 738 | |
| 739 | @cindex bug references, Emacs |
| 740 | Emacs has a nice minor mode called @code{bug-reference}, which can be |
| 741 | used to follow link to issues and pull requests such as @samp{#1234} or |
| 742 | @samp{guix/guix#1234} (@pxref{Bug Reference,,, emacs, The GNU Emacs |
| 743 | Manual}). To set it up, enable it in the relevant modes: |
| 744 | |
| 745 | @lisp |
| 746 | (require 'bug-reference) |
| 747 | (add-hook 'prog-mode-hook #'bug-reference-prog-mode) |
| 748 | (add-hook 'erc-mode-hook #'bug-reference-mode) |
| 749 | ;; Add extra hooks for your mail user agent: Gnus, mu4e, etc. |
| 750 | @end lisp |
| 751 | |
| 752 | When working from a Git checkout of Guix, setup is automatic: |
| 753 | @code{bug-reference} automatically detects that the project is hosted on |
| 754 | Codeberg and infers the issue and pull request URL from there. |
| 755 | |
| 756 | @node Guile Studio |
| 757 | @subsection Guile Studio |
| 758 | |
| 759 | Guile Studio is a pre-configured Emacs with mostly everything you need |
| 760 | to start hacking in Guile. If you are not familiar with Emacs it makes |
| 761 | the transition easier for you. |
| 762 | |
| 763 | @example |
| 764 | guix install guile-studio |
| 765 | @end example |
| 766 | |
| 767 | Guile Studio comes with Geiser preinstalled and prepared for action. |
| 768 | |
| 769 | @node Vim and NeoVim |
| 770 | @subsection Vim and NeoVim |
| 771 | |
| 772 | @cindex Vim, for Scheme code editing |
| 773 | Vim (and NeoVim) are also packaged in Guix, in case these popular modal |
| 774 | editors are more to your taste. |
| 775 | |
| 776 | @example |
| 777 | guix install vim |
| 778 | @end example |
| 779 | |
| 780 | If you want to enjoy a similar development experience to that in the perfect |
| 781 | setup, you should install several plugins to configure the editor. Vim (and |
| 782 | NeoVim) have the equivalent to Paredit, |
| 783 | @uref{https://www.vim.org/scripts/script.php?script_id=3998, |
| 784 | @code{paredit.vim}}, that will help you with the structural editing of Scheme |
| 785 | files (the support for very large files is not great, though). |
| 786 | |
| 787 | @example |
| 788 | guix install vim-paredit |
| 789 | @end example |
| 790 | |
| 791 | We also recommend that you run @code{:set autoindent} so that your code is |
| 792 | automatically indented as you type. |
| 793 | |
| 794 | For the interaction with Git, |
| 795 | @uref{https://www.vim.org/scripts/script.php?script_id=2975, |
| 796 | @code{fugitive.vim}} is the most commonly used plugin: |
| 797 | |
| 798 | @example |
| 799 | guix install vim-fugitive |
| 800 | @end example |
| 801 | |
| 802 | And of course if you want to interact with Guix directly from inside of |
| 803 | vim, using the built-in terminal emulator, we have our very own |
| 804 | @code{guix.vim} package! |
| 805 | |
| 806 | @example |
| 807 | guix install vim-guix-vim |
| 808 | @end example |
| 809 | |
| 810 | In NeoVim you can even make a similar setup to Geiser using |
| 811 | @url{https://conjure.fun/, Conjure} that lets you connect to a running Guile |
| 812 | process and inject your code there live (sadly it's not packaged in Guix yet). |
| 813 | |
| 814 | |
| 815 | @node Source Tree Structure |
| 816 | @section Source Tree Structure |
| 817 | |
| 818 | @cindex structure, of the source tree |
| 819 | If you're willing to contribute to Guix beyond packages, or if you'd |
| 820 | like to learn how it all fits together, this section provides a guided |
| 821 | tour in the code base that you may find useful. |
| 822 | |
| 823 | Overall, the Guix source tree contains almost exclusively Guile |
| 824 | @dfn{modules}, each of which can be seen as an independent library |
| 825 | (@pxref{Modules,,, guile, GNU Guile Reference Manual}). |
| 826 | |
| 827 | The following table gives an overview of the main directories and what |
| 828 | they contain. Remember that in Guile, each module name is derived from |
| 829 | its file name---e.g., the module in file @file{guix/packages.scm} is |
| 830 | called @code{(guix packages)}. |
| 831 | |
| 832 | @table @file |
| 833 | @item guix |
| 834 | This is the location of core Guix mechanisms. To illustrate what is |
| 835 | meant by ``core'', here are a few examples, starting from low-level |
| 836 | tools and going towards higher-level tools: |
| 837 | |
| 838 | @table @code |
| 839 | @item (guix store) |
| 840 | Connecting to and interacting with the build daemon (@pxref{The Store}). |
| 841 | @item (guix derivations) |
| 842 | Creating derivations (@pxref{Derivations}). |
| 843 | @item (guix gexps) |
| 844 | Writing G-expressions (@pxref{G-Expressions}). |
| 845 | @item (guix packages) |
| 846 | Defining packages and origins (@pxref{package Reference}). |
| 847 | @item (guix download) |
| 848 | @itemx (guix git-download) |
| 849 | The @code{url-fetch} and @code{git-fetch} origin download methods |
| 850 | (@pxref{origin Reference}). |
| 851 | @item (guix swh) |
| 852 | Fetching source code from the |
| 853 | @uref{https://archive.softwareheritage.org,Software Heritage archive}. |
| 854 | @item (guix search-paths) |
| 855 | Implementing search paths (@pxref{Search Paths}). |
| 856 | @item (guix build-system) |
| 857 | The build system interface (@pxref{Build Systems}). |
| 858 | @item (guix profiles) |
| 859 | Implementing profiles. |
| 860 | @end table |
| 861 | |
| 862 | @cindex build system, directory structure |
| 863 | @item guix/build-system |
| 864 | This directory contains specific build system implementations |
| 865 | (@pxref{Build Systems}), such as: |
| 866 | |
| 867 | @table @code |
| 868 | @item (guix build-system gnu) |
| 869 | the GNU build system; |
| 870 | @item (guix build-system cmake) |
| 871 | the CMake build system; |
| 872 | @item (guix build-system pyproject) |
| 873 | The Python ``pyproject'' build system. |
| 874 | @end table |
| 875 | |
| 876 | @item guix/build |
| 877 | This contains code generally used on the ``build side'' |
| 878 | (@pxref{G-Expressions, strata of code}). This includes code used to |
| 879 | build packages or other operating system components, as well as |
| 880 | utilities: |
| 881 | |
| 882 | @table @code |
| 883 | @item (guix build utils) |
| 884 | Utilities for package definitions and more (@pxref{Build Utilities}). |
| 885 | @item (guix build gnu-build-system) |
| 886 | @itemx (guix build cmake-build-system) |
| 887 | @itemx (guix build pyproject-build-system) |
| 888 | Implementation of build systems, and in particular definition of their |
| 889 | build phases (@pxref{Build Phases}). |
| 890 | @item (guix build syscalls) |
| 891 | Interface to the C library and to Linux system calls. |
| 892 | @end table |
| 893 | |
| 894 | @cindex command-line tools, as Guile modules |
| 895 | @cindex command modules |
| 896 | @item guix/scripts |
| 897 | This contains modules corresponding to @command{guix} sub-commands. For |
| 898 | example, the @code{(guix scripts shell)} module exports the |
| 899 | @code{guix-shell} procedure, which directly corresponds to the |
| 900 | @command{guix shell} command (@pxref{Invoking guix shell}). |
| 901 | |
| 902 | @cindex importer modules |
| 903 | @item guix/import |
| 904 | This contains supporting code for the importers and updaters |
| 905 | (@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}). For |
| 906 | example, @code{(guix import pypi)} defines the interface to PyPI, which |
| 907 | is used by the @command{guix import pypi} command. |
| 908 | @end table |
| 909 | |
| 910 | The directories we have seen so far all live under @file{guix/}. The |
| 911 | other important place is the @file{gnu/} directory, which contains |
| 912 | primarily package definitions as well as libraries and tools for Guix |
| 913 | System (@pxref{System Configuration}) and Guix Home (@pxref{Home |
| 914 | Configuration}), all of which build upon functionality provided by |
| 915 | @code{(guix @dots{})} modules@footnote{For this reason, @code{(guix |
| 916 | @dots{})} modules must generally not depend on @code{(gnu @dots{})} |
| 917 | modules, with notable exceptions: @code{(guix build-system @dots{})} |
| 918 | modules may look up packages at run time---e.g., @code{(guix |
| 919 | build-system cmake)} needs to access the @code{cmake} variable at run |
| 920 | time---, @code{(guix scripts @dots{})} often rely on @code{(gnu @dots{})} |
| 921 | modules, and the same goes for some of the @code{(guix import @dots{})} |
| 922 | modules.}. |
| 923 | |
| 924 | @table @file |
| 925 | @cindex package modules |
| 926 | @item gnu/packages |
| 927 | This is by far the most crowded directory of the source tree: it |
| 928 | contains @dfn{package modules} that export package definitions |
| 929 | (@pxref{Package Modules}). A few examples: |
| 930 | |
| 931 | @table @code |
| 932 | @item (gnu packages base) |
| 933 | Module providing ``base'' packages: @code{glibc}, @code{coreutils}, |
| 934 | @code{grep}, etc. |
| 935 | @item (gnu packages guile) |
| 936 | Guile and core Guile packages. |
| 937 | @item (gnu packages linux) |
| 938 | The Linux-libre kernel and related packages. |
| 939 | @item (gnu packages python) |
| 940 | Python and core Python packages. |
| 941 | @item (gnu packages python-xyz) |
| 942 | Miscellaneous Python packages (we were not very creative). |
| 943 | @end table |
| 944 | |
| 945 | In any case, you can jump to a package definition using @command{guix |
| 946 | edit} (@pxref{Invoking guix edit}) and view its location with |
| 947 | @command{guix show} (@pxref{Invoking guix package}). |
| 948 | |
| 949 | @findex search-patches |
| 950 | @item gnu/packages/patches |
| 951 | This directory contains patches applied against packages and obtained |
| 952 | using the @code{search-patches} procedure. |
| 953 | |
| 954 | @item gnu/services |
| 955 | This contains service definitions, primarily for Guix System |
| 956 | (@pxref{Services}) but some of them are adapted and reused for Guix Home |
| 957 | as we will see below. Examples: |
| 958 | |
| 959 | @table @code |
| 960 | @item (gnu services) |
| 961 | The service framework itself, which defines the service and service type |
| 962 | data types (@pxref{Service Composition}). |
| 963 | @item (gnu services base) |
| 964 | ``Base'' services (@pxref{Base Services}). |
| 965 | @item (gnu services desktop) |
| 966 | ``Desktop'' services (@pxref{Desktop Services}). |
| 967 | @item (gnu services shepherd) |
| 968 | Support for Shepherd services (@pxref{Shepherd Services}). |
| 969 | @end table |
| 970 | |
| 971 | You can jump to a service definition using @command{guix system edit} |
| 972 | and view its location with @command{guix system search} (@pxref{Invoking |
| 973 | guix system}). |
| 974 | |
| 975 | @item gnu/system |
| 976 | These are core Guix System modules, such as: |
| 977 | |
| 978 | @table @code |
| 979 | @item (gnu system) |
| 980 | Defines @code{operating-system} (@pxref{operating-system Reference}). |
| 981 | @item (gnu system file-systems) |
| 982 | Defines @code{file-system} (@pxref{File Systems}). |
| 983 | @item (gnu system mapped-devices) |
| 984 | Defines @code{mapped-device} (@pxref{Mapped Devices}). |
| 985 | @end table |
| 986 | |
| 987 | @item gnu/build |
| 988 | These are modules that are either used on the ``build side'' when |
| 989 | building operating systems or packages, or at run time by operating |
| 990 | systems. |
| 991 | |
| 992 | @table @code |
| 993 | @item (gnu build accounts) |
| 994 | Creating @file{/etc/passwd}, @file{/etc/shadow}, etc. (@pxref{User |
| 995 | Accounts}). |
| 996 | @item (gnu build activation) |
| 997 | Activating an operating system at boot time or reconfiguration time. |
| 998 | @item (gnu build file-systems) |
| 999 | Searching, checking, and mounting file systems. |
| 1000 | @item (gnu build linux-boot) |
| 1001 | @itemx (gnu build hurd-boot) |
| 1002 | Booting GNU/Linux and GNU/Hurd operating systems. |
| 1003 | @item (gnu build linux-initrd) |
| 1004 | Creating a Linux initial RAM disk (@pxref{Initial RAM Disk}). |
| 1005 | @end table |
| 1006 | |
| 1007 | @item gnu/home |
| 1008 | This contains all things Guix Home (@pxref{Home Configuration}); |
| 1009 | examples: |
| 1010 | |
| 1011 | @table @code |
| 1012 | @item (gnu home services) |
| 1013 | Core services such as @code{home-files-service-type}. |
| 1014 | @item (gnu home services ssh) |
| 1015 | SSH-related services (@pxref{Secure Shell}). |
| 1016 | @end table |
| 1017 | |
| 1018 | @item gnu/installer |
| 1019 | This contains the text-mode graphical system installer (@pxref{Guided |
| 1020 | Graphical Installation}). |
| 1021 | |
| 1022 | @item gnu/machine |
| 1023 | These are the @dfn{machine abstractions} used by @command{guix deploy} |
| 1024 | (@pxref{Invoking guix deploy}). |
| 1025 | |
| 1026 | @item gnu/tests |
| 1027 | This contains system tests---tests that spawn virtual machines to check |
| 1028 | that system services work as expected (@pxref{Running the Test Suite}). |
| 1029 | @end table |
| 1030 | |
| 1031 | Last, there's also a few directories that contain files that are |
| 1032 | @emph{not} Guile modules: |
| 1033 | |
| 1034 | @table @file |
| 1035 | @item nix |
| 1036 | This is the C++ implementation of @command{guix-daemon}, inherited from |
| 1037 | Nix (@pxref{Invoking guix-daemon}). |
| 1038 | |
| 1039 | @item tests |
| 1040 | These are unit tests, each file corresponding more or less to one |
| 1041 | module, in particular @code{(guix @dots{})} modules (@pxref{Running the |
| 1042 | Test Suite}). |
| 1043 | |
| 1044 | @item doc |
| 1045 | This is the documentation in the form of Texinfo files: this manual and |
| 1046 | the Cookbook. @xref{Writing a Texinfo File,,, texinfo, GNU Texinfo}, |
| 1047 | for information on Texinfo markup language. |
| 1048 | |
| 1049 | @item po |
| 1050 | This is the location of translations of Guix itself, of package synopses |
| 1051 | and descriptions, of the manual, and of the cookbook. Note that |
| 1052 | @file{.po} files that live here are pulled directly from Weblate |
| 1053 | (@pxref{Translating Guix}). |
| 1054 | |
| 1055 | @item etc |
| 1056 | Miscellaneous files: shell completions, support for systemd and other |
| 1057 | init systems, Git hooks, etc. |
| 1058 | @end table |
| 1059 | |
| 1060 | With all this, a fair chunk of your operating system is at your |
| 1061 | fingertips! Beyond @command{grep} and @command{git grep}, @pxref{The |
| 1062 | Perfect Setup} on how to navigate code from your editor, and |
| 1063 | @pxref{Using Guix Interactively} for information on how to use Scheme |
| 1064 | modules interactively. Enjoy! |
| 1065 | |
| 1066 | @node Packaging Guidelines |
| 1067 | @section Packaging Guidelines |
| 1068 | |
| 1069 | @cindex packages, creating |
| 1070 | The GNU distribution is nascent and may well lack some of your favorite |
| 1071 | packages. This section describes how you can help make the distribution |
| 1072 | grow. |
| 1073 | |
| 1074 | Free software packages are usually distributed in the form of |
| 1075 | @dfn{source code tarballs}---typically @file{tar.gz} files that contain |
| 1076 | all the source files. Adding a package to the distribution means |
| 1077 | essentially two things: adding a @dfn{recipe} that describes how to |
| 1078 | build the package, including a list of other packages required to build |
| 1079 | it, and adding @dfn{package metadata} along with that recipe, such as a |
| 1080 | description and licensing information. |
| 1081 | |
| 1082 | In Guix all this information is embodied in @dfn{package definitions}. |
| 1083 | Package definitions provide a high-level view of the package. They are |
| 1084 | written using the syntax of the Scheme programming language; in fact, |
| 1085 | for each package we define a variable bound to the package definition, |
| 1086 | and export that variable from a module (@pxref{Package Modules}). |
| 1087 | However, in-depth Scheme knowledge is @emph{not} a prerequisite for |
| 1088 | creating packages. For more information on package definitions, |
| 1089 | @pxref{Defining Packages}. |
| 1090 | |
| 1091 | Once a package definition is in place, stored in a file in the Guix |
| 1092 | source tree, it can be tested using the @command{guix build} command |
| 1093 | (@pxref{Invoking guix build}). For example, assuming the new package is |
| 1094 | called @code{gnew}, you may run this command from the Guix build tree |
| 1095 | (@pxref{Running Guix Before It Is Installed}): |
| 1096 | |
| 1097 | @example |
| 1098 | ./pre-inst-env guix build gnew --keep-failed |
| 1099 | @end example |
| 1100 | |
| 1101 | Using @code{--keep-failed} makes it easier to debug build failures since |
| 1102 | it provides access to the failed build tree. Another useful |
| 1103 | command-line option when debugging is @code{--log-file}, to access the |
| 1104 | build log. |
| 1105 | |
| 1106 | If the package is unknown to the @command{guix} command, it may be that |
| 1107 | the source file contains a syntax error, or lacks a @code{define-public} |
| 1108 | clause to export the package variable. To figure it out, you may load |
| 1109 | the module from Guile to get more information about the actual error: |
| 1110 | |
| 1111 | @example |
| 1112 | ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' |
| 1113 | @end example |
| 1114 | |
| 1115 | Once your package builds correctly, please send us a patch |
| 1116 | (@pxref{Submitting Patches}). Well, if you need help, we will be happy to |
| 1117 | help you too. Once the patch is committed in the Guix repository, the |
| 1118 | new package automatically gets built on the supported platforms by |
| 1119 | @url{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration system}. |
| 1120 | |
| 1121 | @cindex substituter |
| 1122 | Users can obtain the new package definition simply by running |
| 1123 | @command{guix pull} (@pxref{Invoking guix pull}). When |
| 1124 | @code{@value{SUBSTITUTE-SERVER-1}} is done building the package, installing the |
| 1125 | package automatically downloads binaries from there |
| 1126 | (@pxref{Substitutes}). The only place where human intervention is |
| 1127 | needed is to review and apply the patch. |
| 1128 | |
| 1129 | |
| 1130 | @menu |
| 1131 | * Software Freedom:: What may go into the distribution. |
| 1132 | * Extracting Bundled Dependencies:: Why do we unbundle dependencies. |
| 1133 | * Package Naming:: What's in a name? |
| 1134 | * Version Numbers:: When the name is not enough. |
| 1135 | * Synopses and Descriptions:: Helping users find the right package. |
| 1136 | * Snippets versus Phases:: Whether to use a snippet, or a build phase. |
| 1137 | * Cyclic Module Dependencies:: Going full circle. |
| 1138 | * Bulk Updates:: This Little Maneuver's Gonna Cost Us 51 Years. |
| 1139 | * Emacs Packages:: Your Elisp fix. |
| 1140 | * Python Modules:: A touch of British comedy. |
| 1141 | * Perl Modules:: Little pearls. |
| 1142 | * Java Packages:: Coffee break. |
| 1143 | * Rust Crates:: Beware of oxidation. |
| 1144 | * Elm Packages:: Trees of browser code |
| 1145 | * Fonts:: Fond of fonts. |
| 1146 | @end menu |
| 1147 | |
| 1148 | @node Software Freedom |
| 1149 | @subsection Software Freedom |
| 1150 | |
| 1151 | @c Adapted from http://www.gnu.org/philosophy/philosophy.html. |
| 1152 | @cindex free software |
| 1153 | The GNU operating system has been developed so that users can have |
| 1154 | freedom in their computing. GNU is @dfn{free software}, meaning that |
| 1155 | users have the @url{https://www.gnu.org/philosophy/free-sw.html,four |
| 1156 | essential freedoms}: to run the program, to study and change the program |
| 1157 | in source code form, to redistribute exact copies, and to distribute |
| 1158 | modified versions. Packages found in the GNU distribution provide only |
| 1159 | software that conveys these four freedoms. |
| 1160 | |
| 1161 | In addition, the GNU distribution follow the |
| 1162 | @url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free |
| 1163 | software distribution guidelines}. Among other things, these guidelines |
| 1164 | reject non-free firmware, recommendations of non-free software, and |
| 1165 | discuss ways to deal with trademarks and patents. |
| 1166 | |
| 1167 | Some otherwise free upstream package sources contain a small and optional |
| 1168 | subset that violates the above guidelines, for instance because this subset |
| 1169 | is itself non-free code. When that happens, the offending items are removed |
| 1170 | with appropriate patches or code snippets in the @code{origin} form of the |
| 1171 | package (@pxref{Defining Packages}). This way, @code{guix |
| 1172 | build --source} returns the ``freed'' source rather than the unmodified |
| 1173 | upstream source. |
| 1174 | |
| 1175 | @node Extracting Bundled Dependencies |
| 1176 | @subsection Extracting Bundled Dependencies |
| 1177 | @cindex bundling |
| 1178 | @cindex vendoring |
| 1179 | @cindex bundled dependencies |
| 1180 | @cindex vendored dependencies |
| 1181 | |
| 1182 | In Guix every package is supposed to be fully built from source |
| 1183 | (@pxref{Bootstrapping}). This is at the heart of the security and user |
| 1184 | freedom guarantees provided by the distribution, and it is what allows |
| 1185 | Guix to correctly reason about the package graph, to apply transversal |
| 1186 | changes (say, a security update on a single library) and have them |
| 1187 | propagate to every dependent package. |
| 1188 | |
| 1189 | Some projects have the habit of distributing the source code of their |
| 1190 | dependencies inside their release tarball or version controlled source |
| 1191 | tree. This practice is called @dfn{bundling} and the dependencies |
| 1192 | shipped this way are called @dfn{bundled dependencies} or in some cases |
| 1193 | @dfn{vendored dependencies}. Common manifestations are a @file{vendor/} |
| 1194 | directory in Go projects, a checked in @file{node_modules/} for |
| 1195 | JavaScript, a populated @file{.cargo/vendor/} for Rust, or copies of |
| 1196 | small C libraries shipped inside another project's tree. |
| 1197 | |
| 1198 | Bundling dependencies conflicts with several Guix invariants: |
| 1199 | |
| 1200 | @itemize |
| 1201 | @item When a change must be made in a library---e.g., applying a security fix |
| 1202 | or removing pre-generated code---that change would need to be repeated |
| 1203 | in every single package that bundles it. |
| 1204 | @item Guix mainline ships only free software: bundled trees frequently contain |
| 1205 | minified blobs whose preferred form for modification is missing |
| 1206 | (@pxref{Software Freedom}). |
| 1207 | @item Duplicated source code inflates the closure size and makes |
| 1208 | @command{guix size} (@pxref{Invoking guix size}) and @command{guix |
| 1209 | graph} (@pxref{Invoking guix graph}) less useful as auditing tools. |
| 1210 | @end itemize |
| 1211 | |
| 1212 | For these reasons, we do our best to remove bundled dependencies before |
| 1213 | submitting a package. |
| 1214 | |
| 1215 | @subsubheading Removing Bundled Code |
| 1216 | |
| 1217 | Bundled dependencies should be removed in the package's @code{origin} |
| 1218 | record, typically using a snippet or a patch, so that the source |
| 1219 | returned by @command{guix build --source} corresponds to truly free, |
| 1220 | unbundled sources (@pxref{Snippets versus Phases}). When the removal is |
| 1221 | more involved, for example because it requires regenerating build files |
| 1222 | or rewriting import paths, it is acceptable to do it in a build phase |
| 1223 | instead. |
| 1224 | |
| 1225 | Once the bundled tree is gone, the package must be built against |
| 1226 | existing Guix packages of the same dependencies. When such packages do |
| 1227 | not yet exist, they must be added. |
| 1228 | |
| 1229 | @subsubheading Exceptions |
| 1230 | |
| 1231 | Removing bundled code is the rule, but in case a bundled dependency has |
| 1232 | been changed up to the point that it isn't possible to build a package |
| 1233 | with the unbundled version of the dependency, it can be considered as |
| 1234 | part of the source tree it lives in. In general we don't care about |
| 1235 | upstream's reason for bundling, only the practicality of the unbundling |
| 1236 | job. |
| 1237 | |
| 1238 | @node Package Naming |
| 1239 | @subsection Package Naming |
| 1240 | |
| 1241 | @cindex package name |
| 1242 | A package actually has two names associated with it. |
| 1243 | First, there is the name of the @emph{Scheme variable}, the one following |
| 1244 | @code{define-public}. By this name, the package can be made known in the |
| 1245 | Scheme code, for instance as input to another package. Second, there is |
| 1246 | the string in the @code{name} field of a package definition. This name |
| 1247 | is used by package management commands such as |
| 1248 | @command{guix package} and @command{guix build}. |
| 1249 | |
| 1250 | Both are usually the same and correspond to the lowercase conversion of |
| 1251 | the project name chosen upstream, with underscores replaced with |
| 1252 | hyphens. For instance, GNUnet is available as @code{gnunet}, and |
| 1253 | SDL_net as @code{sdl-net}. |
| 1254 | |
| 1255 | A noteworthy exception to this rule is when the project name is only a |
| 1256 | single character, or if an older maintained project with the same name |
| 1257 | already exists---regardless of whether it has already been packaged for |
| 1258 | Guix. Use common sense to make such names unambiguous and meaningful. |
| 1259 | For example, Guix's package for the shell called ``s'' upstream is |
| 1260 | @code{s-shell} and @emph{not} @code{s}. Feel free to ask your fellow |
| 1261 | hackers for inspiration. |
| 1262 | |
| 1263 | We do not add @code{lib} prefixes for library packages, unless these are |
| 1264 | already part of the official project name. But @pxref{Python |
| 1265 | Modules} and @ref{Perl Modules} for special rules concerning modules for |
| 1266 | the Python and Perl languages. |
| 1267 | |
| 1268 | Font package names are handled differently, @pxref{Fonts}. |
| 1269 | |
| 1270 | |
| 1271 | @node Version Numbers |
| 1272 | @subsection Version Numbers |
| 1273 | |
| 1274 | @cindex package version |
| 1275 | We usually package only the latest version of a given free software |
| 1276 | project. But sometimes, for instance for incompatible library versions, |
| 1277 | two (or more) versions of the same package are needed. These require |
| 1278 | different Scheme variable names. We use the name as defined |
| 1279 | in @ref{Package Naming} |
| 1280 | for the most recent version; previous versions use the same name, suffixed |
| 1281 | by @code{-} and the smallest prefix of the version number that may |
| 1282 | distinguish the two versions. |
| 1283 | |
| 1284 | The name inside the package definition is the same for all versions of a |
| 1285 | package and does not contain any version number. |
| 1286 | |
| 1287 | For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: |
| 1288 | |
| 1289 | @lisp |
| 1290 | (define-public gtk+ |
| 1291 | (package |
| 1292 | (name "gtk+") |
| 1293 | (version "3.9.12") |
| 1294 | ...)) |
| 1295 | (define-public gtk+-2 |
| 1296 | (package |
| 1297 | (name "gtk+") |
| 1298 | (version "2.24.20") |
| 1299 | ...)) |
| 1300 | @end lisp |
| 1301 | If we also wanted GTK+ 3.8.2, this would be packaged as |
| 1302 | @lisp |
| 1303 | (define-public gtk+-3.8 |
| 1304 | (package |
| 1305 | (name "gtk+") |
| 1306 | (version "3.8.2") |
| 1307 | ...)) |
| 1308 | @end lisp |
| 1309 | |
| 1310 | @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, |
| 1311 | @c for a discussion of what follows. |
| 1312 | @cindex version number, for VCS snapshots |
| 1313 | Occasionally, we package snapshots of upstream's version control system |
| 1314 | (VCS) instead of formal releases. This should remain exceptional, |
| 1315 | because it is up to upstream developers to clarify what the stable |
| 1316 | release is. Yet, it is sometimes necessary. So, what should we put in |
| 1317 | the @code{version} field? |
| 1318 | |
| 1319 | Clearly, we need to make the commit identifier of the VCS snapshot |
| 1320 | visible in the version string, but we also need to make sure that the |
| 1321 | version string is monotonically increasing so that @command{guix package |
| 1322 | --upgrade} can determine which version is newer. Since commit |
| 1323 | identifiers, notably with Git, are not monotonically increasing, we add |
| 1324 | a revision number that we increase each time we upgrade to a newer |
| 1325 | snapshot. The resulting version string looks like this: |
| 1326 | |
| 1327 | @example |
| 1328 | 2.0.11-3.cabba9e |
| 1329 | ^ ^ ^ |
| 1330 | | | `-- upstream commit ID |
| 1331 | | | |
| 1332 | | `--- Guix package revision |
| 1333 | | |
| 1334 | latest upstream version |
| 1335 | @end example |
| 1336 | |
| 1337 | It is a good idea to strip commit identifiers in the @code{version} |
| 1338 | field to, say, 7 digits. It avoids an aesthetic annoyance (assuming |
| 1339 | aesthetics have a role to play here) as well as problems related to OS |
| 1340 | limits such as the maximum shebang length (127 bytes for the Linux |
| 1341 | kernel). There are helper functions for doing this for packages using |
| 1342 | @code{git-fetch} or @code{hg-fetch} (see below). It is best to use the |
| 1343 | full commit identifiers in @code{origin}s, though, to avoid ambiguities. |
| 1344 | A typical package definition may look like this: |
| 1345 | |
| 1346 | |
| 1347 | @lisp |
| 1348 | (define my-package |
| 1349 | (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") |
| 1350 | (revision "1")) ;Guix package revision |
| 1351 | (package |
| 1352 | (version (git-version "0.9" revision commit)) |
| 1353 | (source (origin |
| 1354 | (method git-fetch) |
| 1355 | (uri (git-reference |
| 1356 | (url "git://example.org/my-package.git") |
| 1357 | (commit commit))) |
| 1358 | (sha256 (base32 "1mbikn@dots{}")) |
| 1359 | (file-name (git-file-name name version)))) |
| 1360 | ;; @dots{} |
| 1361 | ))) |
| 1362 | @end lisp |
| 1363 | |
| 1364 | @deffn {Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT} |
| 1365 | Return the version string for packages using @code{git-fetch}. |
| 1366 | |
| 1367 | @lisp |
| 1368 | (git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05") |
| 1369 | @result{} "0.2.3-0.93818c9" |
| 1370 | @end lisp |
| 1371 | @end deffn |
| 1372 | |
| 1373 | @deffn {Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET} |
| 1374 | Return the version string for packages using @code{hg-fetch}. It works |
| 1375 | in the same way as @code{git-version}. |
| 1376 | @end deffn |
| 1377 | |
| 1378 | @node Synopses and Descriptions |
| 1379 | @subsection Synopses and Descriptions |
| 1380 | |
| 1381 | @cindex package description |
| 1382 | @cindex package synopsis |
| 1383 | As we have seen before, each package in GNU@tie{}Guix includes a |
| 1384 | synopsis and a description (@pxref{Defining Packages}). Synopses and |
| 1385 | descriptions are important: They are what @command{guix package |
| 1386 | --search} searches, and a crucial piece of information to help users |
| 1387 | determine whether a given package suits their needs. Consequently, |
| 1388 | packagers should pay attention to what goes into them. |
| 1389 | |
| 1390 | Synopses must start with a capital letter and must not end with a |
| 1391 | period. They must not start with ``a'' or ``the'', which usually does |
| 1392 | not bring anything; for instance, prefer ``File-frobbing tool'' over ``A |
| 1393 | tool that frobs files''. The synopsis should say what the package |
| 1394 | is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is |
| 1395 | used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines |
| 1396 | matching a pattern''. |
| 1397 | |
| 1398 | Keep in mind that the synopsis must be meaningful for a very wide |
| 1399 | audience. For example, ``Manipulate alignments in the SAM format'' |
| 1400 | might make sense for a seasoned bioinformatics researcher, but might be |
| 1401 | fairly unhelpful or even misleading to a non-specialized audience. It |
| 1402 | is a good idea to come up with a synopsis that gives an idea of the |
| 1403 | application domain of the package. In this example, this might give |
| 1404 | something like ``Manipulate nucleotide sequence alignments'', which |
| 1405 | hopefully gives the user a better idea of whether this is what they are |
| 1406 | looking for. |
| 1407 | |
| 1408 | Descriptions should take between five and ten lines. Use full |
| 1409 | sentences, and avoid using acronyms without first introducing them. |
| 1410 | Please avoid marketing phrases such as ``world-leading'', |
| 1411 | ``industrial-strength'', and ``next-generation'', and avoid superlatives |
| 1412 | like ``the most advanced''---they are not helpful to users looking for a |
| 1413 | package and may even sound suspicious. Instead, try to be factual, |
| 1414 | mentioning use cases and features. |
| 1415 | |
| 1416 | @cindex Texinfo markup, in package descriptions |
| 1417 | Descriptions can include Texinfo markup, which is useful to introduce |
| 1418 | ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or |
| 1419 | hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you |
| 1420 | should be careful when using some characters for example @samp{@@} and |
| 1421 | curly braces which are the basic special characters in Texinfo |
| 1422 | (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces |
| 1423 | such as @command{guix show} take care of rendering it |
| 1424 | appropriately. |
| 1425 | |
| 1426 | Synopses and descriptions are translated by volunteers |
| 1427 | @uref{https://translate.codeberg.org/projects/guix/packages, at |
| 1428 | Weblate} so that as many users as possible can read them in |
| 1429 | their native language. User interfaces search them and display them in |
| 1430 | the language specified by the current locale. |
| 1431 | |
| 1432 | To allow @command{xgettext} to extract them as translatable strings, |
| 1433 | synopses and descriptions @emph{must be literal strings}. This means |
| 1434 | that you cannot use @code{string-append} or @code{format} to construct |
| 1435 | these strings: |
| 1436 | |
| 1437 | @lisp |
| 1438 | (package |
| 1439 | ;; @dots{} |
| 1440 | (synopsis "This is translatable") |
| 1441 | (description (string-append "This is " "*not*" " translatable."))) |
| 1442 | @end lisp |
| 1443 | |
| 1444 | Translation is a lot of work so, as a packager, please pay even more |
| 1445 | attention to your synopses and descriptions as every change may entail |
| 1446 | additional work for translators. In order to help them, it is possible |
| 1447 | to make recommendations or instructions visible to them by inserting |
| 1448 | special comments like this (@pxref{xgettext Invocation,,, gettext, GNU |
| 1449 | Gettext}): |
| 1450 | |
| 1451 | @lisp |
| 1452 | ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. |
| 1453 | (description "ARandR is designed to provide a simple visual front end |
| 1454 | for the X11 resize-and-rotate (RandR) extension. @dots{}") |
| 1455 | @end lisp |
| 1456 | |
| 1457 | @node Snippets versus Phases |
| 1458 | @subsection Snippets versus Phases |
| 1459 | |
| 1460 | @cindex snippets, when to use |
| 1461 | The boundary between using an origin snippet versus a build phase to |
| 1462 | modify the sources of a package can be elusive. Origin snippets are |
| 1463 | typically used to remove unwanted files such as bundled libraries, |
| 1464 | nonfree sources, or to apply simple substitutions. The source derived |
| 1465 | from an origin should produce a source that can be used to build the |
| 1466 | package on any system that the upstream package supports (i.e., act as |
| 1467 | the corresponding source). In particular, origin snippets must not |
| 1468 | embed store items in the sources; such patching should rather be done |
| 1469 | using build phases. Refer to the @code{origin} record documentation for |
| 1470 | more information (@pxref{origin Reference}). |
| 1471 | |
| 1472 | @node Cyclic Module Dependencies |
| 1473 | @subsection Cyclic Module Dependencies |
| 1474 | |
| 1475 | While there cannot be circular dependencies between packages, Guile's |
| 1476 | lax module loading mechanism allows circular dependencies between Guile |
| 1477 | modules, which doesn't cause problems as long as the following |
| 1478 | conditions are followed for two modules part of a dependency cycle: |
| 1479 | |
| 1480 | @cindex rules to cope with circular module dependencies |
| 1481 | @enumerate |
| 1482 | @item |
| 1483 | Macros are not shared between the co-dependent modules |
| 1484 | @item |
| 1485 | Top-level variables are only referenced in delayed (@i{thunked}) package |
| 1486 | fields: @code{arguments}, @code{native-inputs}, @code{inputs}, |
| 1487 | @code{propagated-inputs} or @code{replacement} |
| 1488 | @item |
| 1489 | Procedures referencing top-level variables from another module are not |
| 1490 | called at the top level of a module themselves. |
| 1491 | @end enumerate |
| 1492 | |
| 1493 | Straying away from the above rules may work while there are no |
| 1494 | dependency cycles between modules, but given such cycles are confusing |
| 1495 | and difficult to troubleshoot, it is best to follow the rules to avoid |
| 1496 | introducing problems down the line. |
| 1497 | |
| 1498 | @noindent |
| 1499 | Here is a common trap to avoid: |
| 1500 | |
| 1501 | @lisp |
| 1502 | (define-public avr-binutils |
| 1503 | (package |
| 1504 | (inherit (cross-binutils "avr")) |
| 1505 | (name "avr-binutils"))) |
| 1506 | @end lisp |
| 1507 | |
| 1508 | In the above example, the @code{avr-binutils} package was defined in the |
| 1509 | module @code{(gnu packages avr)}, and the @code{cross-binutils} |
| 1510 | procedure in @code{(gnu packages cross-base)}. Because the |
| 1511 | @code{inherit} field is not delayed (thunked), it is evaluated at the |
| 1512 | top level at load time, which is problematic in the presence of module |
| 1513 | dependency cycles. This could be resolved by turning the package into a |
| 1514 | procedure instead, like: |
| 1515 | |
| 1516 | @lisp |
| 1517 | (define (make-avr-binutils) |
| 1518 | (package |
| 1519 | (inherit (cross-binutils "avr")) |
| 1520 | (name "avr-binutils"))) |
| 1521 | @end lisp |
| 1522 | |
| 1523 | Care would need to be taken to ensure the above procedure is only ever |
| 1524 | used in a package delayed fields or within another procedure also not |
| 1525 | called at the top level. |
| 1526 | |
| 1527 | @node Bulk Updates |
| 1528 | @subsection Bulk Updates |
| 1529 | |
| 1530 | @cindex packaging, maintenance |
| 1531 | Sometimes you may need to update a monotonic collection of grouped |
| 1532 | packages, in a particular module---e.g., @code{(gnu packages astronomy)}. |
| 1533 | Doing so requires refreshing package versions, creating commits |
| 1534 | following guidelines and testing them. Let's say there are 200+ packages |
| 1535 | with fresh versions, you may deal with this task by applying the |
| 1536 | following technique. |
| 1537 | |
| 1538 | Enter a development shell in your local Guix checkout, assuming you |
| 1539 | already ran @code{bootstrap} and @code{configure}: |
| 1540 | |
| 1541 | @example |
| 1542 | ~$ guix shell --development guix |
| 1543 | [env: /gnu/store/@dots{}-profile] |
| 1544 | > ./pre-inst-env guix refresh --select=module:astronomy --update |
| 1545 | > ./pre-inst-env etc/committer.scm |
| 1546 | @end example |
| 1547 | |
| 1548 | The first command updates all packages in @code{(gnu packages |
| 1549 | astronomy)} to the latest versions and writes changes back to the file. |
| 1550 | The second invokes @code{etc/committer.scm} script, a helper script for |
| 1551 | larger scale updates; it identifies each package diff and creates |
| 1552 | corresponding commits with the correct style. |
| 1553 | |
| 1554 | If your machine is powerful enough, you may check that the whole |
| 1555 | collection has no regressions and can still be built successfully: |
| 1556 | @example |
| 1557 | [env: /gnu/store/@dots{}-profile] |
| 1558 | > ./pre-inst-env guix build $(./pre-inst-env guix package -A | awk '/astronomy.scm/@{print $1"@@"$2@}') |
| 1559 | @end example |
| 1560 | |
| 1561 | @node Emacs Packages |
| 1562 | @subsection Emacs Packages |
| 1563 | |
| 1564 | @cindex emacs, packaging |
| 1565 | @cindex elisp, packaging |
| 1566 | Emacs packages should preferably use the Emacs build system |
| 1567 | (@pxref{emacs-build-system}), for uniformity and the benefits provided |
| 1568 | by its build phases, such as the auto-generation of the autoloads file |
| 1569 | and the byte compilation of the sources. |
| 1570 | |
| 1571 | The Elisp dependencies of Emacs packages are typically provided as |
| 1572 | @code{propagated-inputs} when required at run time. As for other |
| 1573 | packages, build or test dependencies should be specified as |
| 1574 | @code{native-inputs}. |
| 1575 | |
| 1576 | Emacs packages sometimes depend on resources directories that should be |
| 1577 | installed along the Elisp files. The @code{#:include} argument can be |
| 1578 | used for that purpose, by specifying a list of regexps to match. The |
| 1579 | best practice when using the @code{#:include} argument is to extend |
| 1580 | rather than override its default value (accessible via the |
| 1581 | @code{%default-include} variable). As an example, a yasnippet extension |
| 1582 | package typically include a @file{snippets} directory, which could be |
| 1583 | copied to the installation directory using: |
| 1584 | |
| 1585 | @lisp |
| 1586 | #:include (cons "^snippets/" %default-include) |
| 1587 | @end lisp |
| 1588 | |
| 1589 | When encountering problems, it is wise to check for the presence of the |
| 1590 | @code{Package-Requires} extension header in the package main source |
| 1591 | file, and whether any dependencies and their versions listed therein are |
| 1592 | satisfied. |
| 1593 | |
| 1594 | @node Python Modules |
| 1595 | @subsection Python Modules |
| 1596 | |
| 1597 | @cindex python |
| 1598 | The standard way to generate a package definition is to use |
| 1599 | @code{guix import pypi <name>}, where @var{name} is the name of the |
| 1600 | Python package on @url{https://pypi.org, PyPI}, see @pxref{Invoking guix |
| 1601 | import}. Please check with @code{guix lint <package-name>} that the |
| 1602 | generated package is valid. |
| 1603 | |
| 1604 | To avoid confusion and naming clashes with other programming languages, |
| 1605 | Python module packages should be prefixed with @code{python-}. |
| 1606 | |
| 1607 | If a project already contains the word @code{python}, please do not |
| 1608 | repeat it; for instance, the module python-dateutil is packaged under |
| 1609 | the name @code{python-dateutil}. If the project name starts with |
| 1610 | @code{py}, it is kept and prefixed as described above (e.g.@: |
| 1611 | @code{python-pytz}). |
| 1612 | |
| 1613 | @quotation Note |
| 1614 | The standard build system for Python packages is Guix's implementation |
| 1615 | of the @url{https://peps.python.org/pep-0517/, formal Python standard} |
| 1616 | for specifying build requirements: @var{pyproject-build-system}. |
| 1617 | The @var{python-build-system} which corresponds to the way Python |
| 1618 | packages were built before PEP517, using the informally specified |
| 1619 | @file{setup.py} file, is now deprecated. @var{pyproject-build-system} |
| 1620 | will eventually be deprecated and renamed into |
| 1621 | @var{python-build-system} after its removal. |
| 1622 | @end quotation |
| 1623 | |
| 1624 | @subsubsection Specifying Dependencies |
| 1625 | @cindex inputs, for Python packages |
| 1626 | |
| 1627 | Dependency information for Python packages is usually available in the |
| 1628 | package source tree, with varying degrees of accuracy: in the |
| 1629 | @file{pyproject.toml} file, the @file{setup.py} file, in |
| 1630 | @file{requirements.txt}, or in @file{tox.ini} (the latter mostly for |
| 1631 | test dependencies). |
| 1632 | |
| 1633 | When editing a recipe for a Python package, the goal is to map these |
| 1634 | dependencies to the appropriate type of ``input'' (@pxref{package |
| 1635 | Reference, inputs}). Although the @code{pypi} importer normally does a |
| 1636 | good job (@pxref{Invoking guix import}), please verify the following |
| 1637 | check list to determine which dependency goes where. |
| 1638 | |
| 1639 | @itemize |
| 1640 | |
| 1641 | @item |
| 1642 | Python is packaged @emph{without} @code{setuptools} and @code{pip} |
| 1643 | installed per default. |
| 1644 | |
| 1645 | @command{guix lint} will warn if @code{pip} or other unneeded |
| 1646 | native-inputs are added. |
| 1647 | |
| 1648 | @item |
| 1649 | Python dependencies required at run time go into |
| 1650 | @code{propagated-inputs}. They are typically defined with the |
| 1651 | @code{install_requires} keyword in @file{setup.py}, or in the |
| 1652 | @file{requirements.txt} file. |
| 1653 | |
| 1654 | @item |
| 1655 | Python packages required only at build time---e.g., those listed under |
| 1656 | @code{build-system.requires} in @file{pyproject.toml} or with the |
| 1657 | @code{setup_requires} keyword in @file{setup.py}---or dependencies only |
| 1658 | for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into |
| 1659 | @code{native-inputs}. The rationale is that (1) they do not need to be |
| 1660 | propagated because they are not needed at run time, and (2) in a |
| 1661 | cross-compilation context, it's the target ``native'' input. |
| 1662 | |
| 1663 | Examples are the @code{pytest}, @code{mock}, and @code{stestr} test |
| 1664 | frameworks. Of course if any of these packages is also required at |
| 1665 | run-time, it needs to go to @code{propagated-inputs}. |
| 1666 | |
| 1667 | @item |
| 1668 | Anything that does not fall in the previous categories goes to |
| 1669 | @code{inputs}, for example programs or C libraries required for building |
| 1670 | Python packages containing C extensions. |
| 1671 | |
| 1672 | @item |
| 1673 | If a Python package has optional dependencies (@code{extras_require}), |
| 1674 | it is up to you to decide whether to add them or not, based on their |
| 1675 | usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix |
| 1676 | size}}). |
| 1677 | |
| 1678 | @end itemize |
| 1679 | |
| 1680 | |
| 1681 | @node Perl Modules |
| 1682 | @subsection Perl Modules |
| 1683 | |
| 1684 | @cindex perl |
| 1685 | Perl programs standing for themselves are named as any other package, |
| 1686 | using the lowercase upstream name. |
| 1687 | For Perl packages containing a single class, we use the lowercase class name, |
| 1688 | replace all occurrences of @code{::} by dashes and prepend the prefix |
| 1689 | @code{perl-}. |
| 1690 | So the class @code{XML::Parser} becomes @code{perl-xml-parser}. |
| 1691 | Modules containing several classes keep their lowercase upstream name and |
| 1692 | are also prepended by @code{perl-}. Such modules tend to have the word |
| 1693 | @code{perl} somewhere in their name, which gets dropped in favor of the |
| 1694 | prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}. |
| 1695 | |
| 1696 | |
| 1697 | @node Java Packages |
| 1698 | @subsection Java Packages |
| 1699 | |
| 1700 | @cindex java |
| 1701 | Java programs standing for themselves are named as any other package, |
| 1702 | using the lowercase upstream name. |
| 1703 | |
| 1704 | To avoid confusion and naming clashes with other programming languages, |
| 1705 | it is desirable that the name of a package for a Java package is |
| 1706 | prefixed with @code{java-}. If a project already contains the word |
| 1707 | @code{java}, we drop this; for instance, the package @code{ngsjava} is |
| 1708 | packaged under the name @code{java-ngs}. |
| 1709 | |
| 1710 | For Java packages containing a single class or a small class hierarchy, |
| 1711 | we use the lowercase class name, replace all occurrences of @code{.} by |
| 1712 | dashes and prepend the prefix @code{java-}. So the class |
| 1713 | @code{apache.commons.cli} becomes package |
| 1714 | @code{java-apache-commons-cli}. |
| 1715 | |
| 1716 | |
| 1717 | @node Rust Crates |
| 1718 | @subsection Rust Crates |
| 1719 | |
| 1720 | @cindex rust |
| 1721 | Rust applications (binary crates) and libraries (library crates) are packaged |
| 1722 | separately. We put our main efforts into applications and only package |
| 1723 | libraries as sources, utilizing automation with a manual focus on unbundling |
| 1724 | vendored dependencies. |
| 1725 | |
| 1726 | Rust applications are treated like any other package and named using the |
| 1727 | lowercase upstream name. When using the Cargo build system (@pxref{Build |
| 1728 | Systems, @code{cargo-build-system}}), Rust applications should have the |
| 1729 | @code{#:install-source?} parameter set to @code{#f}, as this parameter only |
| 1730 | makes sense for libraries. When the package source is a Cargo workspace, |
| 1731 | @code{#:cargo-install-paths} must be set to enable relevant support. |
| 1732 | |
| 1733 | Rust libraries are hidden from the user interface and managed in two modules: |
| 1734 | |
| 1735 | @table @code |
| 1736 | @item (gnu packages rust-crates) |
| 1737 | Source definitions imported from Rust packages' @file{Cargo.lock} via the |
| 1738 | @code{crate} importer (@pxref{Invoking guix import}). |
| 1739 | |
| 1740 | Imported definitions must be checked and have vendored dependencies unbundled |
| 1741 | before being contributed to Guix. |
| 1742 | |
| 1743 | @item (gnu packages rust-sources) |
| 1744 | More complex definitions that need to be full packages. This includes Rust |
| 1745 | libraries requiring external inputs to unbundle and Cargo workspaces. |
| 1746 | |
| 1747 | These libraries should have the @code{#:skip-build?} parameter set to @code{#t}. |
| 1748 | For Cargo workspaces, @code{#:cargo-package-crates} must be set. |
| 1749 | |
| 1750 | Since they are added manually, they follow the usual naming convention for Guix |
| 1751 | packages (@pxref{Package Naming}), with a @code{rust-} prefix. |
| 1752 | |
| 1753 | In the Rust community it is common for multiple incompatible versions of a |
| 1754 | package to be used at any given time, so all libraries should have a versioned |
| 1755 | suffix. The versioned suffix is the left-most non-zero digit (and any leading |
| 1756 | zeros, of course). This follows the ``caret'' version scheme intended by Cargo. |
| 1757 | Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}. |
| 1758 | |
| 1759 | In practice we often package development snapshots of Rust libraries and can't |
| 1760 | simply identify them by version. In this case, the complete version information |
| 1761 | can be turned into a version string via @code{git-version}, for example |
| 1762 | @code{rust-pipewire-0.8.0.fd3d8f7} and @code{rust-pubgrub-0.3.0.b70cf70}. |
| 1763 | @end table |
| 1764 | |
| 1765 | When contributing Rust packages, we should have all modifications to these |
| 1766 | two modules, in the same commit as the package we are contributing. |
| 1767 | |
| 1768 | To avoid merge conflicts with changes from multiple branches, these two modules |
| 1769 | are maintained by the Rust team (@pxref{Teams}). |
| 1770 | |
| 1771 | @quotation Warning |
| 1772 | The @code{(gnu packages rust-crates)} module must not be referenced |
| 1773 | directly, lest it introduce the risk of cyclic module dependencies |
| 1774 | (@pxref{Cyclic Module Dependencies}). Instead, the @code{cargo-inputs} |
| 1775 | procedure from the @code{(guix build-sytem cargo)} module must be used |
| 1776 | to lookup input lists generated by the lockfile importer. |
| 1777 | @end quotation |
| 1778 | |
| 1779 | @cindex cargo inputs |
| 1780 | @findex define-cargo-inputs |
| 1781 | @findex lookup-cargo-inputs |
| 1782 | @deffn {Procedure} cargo-inputs name [#:module '(gnu packages rust-crates)] |
| 1783 | Lookup Cargo inputs for @var{name} in @var{module}, return an empty list if |
| 1784 | unavailable. |
| 1785 | |
| 1786 | @var{name} must be consistent with the one used in lockfile importer invocation, |
| 1787 | usually matching the variable name of the package: |
| 1788 | |
| 1789 | @example |
| 1790 | $ guix import -i @file{gnu/packages/rust-crates.scm} crate -f @file{/path/to/Cargo.lock} @var{name} |
| 1791 | @end example |
| 1792 | |
| 1793 | @var{module} must export a public interface @code{lookup-cargo-inputs}, a |
| 1794 | template is available in the @file{etc/teams/rust} directory of Guix source |
| 1795 | tree. |
| 1796 | @end deffn |
| 1797 | |
| 1798 | @xref{Packaging Rust Crates,,, guix-cookbook, GNU Guix Cookbook}, for |
| 1799 | packaging workflow. |
| 1800 | |
| 1801 | @subsubsection Commit messages |
| 1802 | |
| 1803 | The commit message must have a general brief mention to entry changes |
| 1804 | in @code{(gnu packages rust-crates)}. For changes in @code{(gnu packages |
| 1805 | rust-sources)}, the commit message must explicitly mention all changes to the |
| 1806 | packages. |
| 1807 | |
| 1808 | Here are some examples for different situations: |
| 1809 | |
| 1810 | @itemize |
| 1811 | |
| 1812 | @item |
| 1813 | Adding a new Rust package: |
| 1814 | |
| 1815 | @example |
| 1816 | gnu: Add catppuccin-whiskers. |
| 1817 | |
| 1818 | * gnu/packages/rust-apps.scm (catppuccin-whiskers): New variable. |
| 1819 | * gnu/packages/rust-crates.scm (lookup-cargo-inputs) |
| 1820 | [catppuccin-whiskers]: New entry. |
| 1821 | @end example |
| 1822 | |
| 1823 | @item |
| 1824 | Updating a simple package: |
| 1825 | |
| 1826 | @example |
| 1827 | gnu: watchexec: Update to 2.3.2. |
| 1828 | |
| 1829 | * gnu/packages/rust-apps.scm (watchexec): Update to 2.3.2. |
| 1830 | * gnu/packages/rust-crates.scm (lookup-cargo-inputs)[watchexec]: |
| 1831 | Update entry. |
| 1832 | @end example |
| 1833 | |
| 1834 | @item |
| 1835 | Updating a package with sources: |
| 1836 | |
| 1837 | @example |
| 1838 | gnu: typst: Update to 0.14.0. |
| 1839 | |
| 1840 | * gnu/packages/rust-apps.scm (typst): Update to 0.14.0. |
| 1841 | [arguments]<#:rust>: Use rust-1.88. |
| 1842 | * gnu/packages/rust-crates.scm (lookup-cargo-inputs)[typst]: Update |
| 1843 | entry. |
| 1844 | [rust-syntect-5]: Rename to rust-syntect-5.2. |
| 1845 | [rust-syntect-5.3]: New entry. |
| 1846 | * gnu/packages/rust-sources.scm (rust-hypher-0.1): Update to 0.1.6. |
| 1847 | (rust-syntect-5): Rename to rust-syntect-5.2. |
| 1848 | [inputs]: Rename cargo-inputs rust-syntect-5 to rust-syntect-5.2. |
| 1849 | (rust-syntect-5.3): New variable. |
| 1850 | @end example |
| 1851 | |
| 1852 | @end itemize |
| 1853 | |
| 1854 | @subsubsection Resolving merge conflicts in Pull Requests |
| 1855 | |
| 1856 | For Rust crates, the recommended way to solve merge conflicts is to drop all |
| 1857 | changes to @code{gnu/packages/rust-crates.scm}, rebase onto the desired branch |
| 1858 | and run the lockfile importer again, manually adding back all relevant snippets |
| 1859 | (if any). |
| 1860 | |
| 1861 | @xref{Common Workflow for Resolving Merge Conflicts on Existing Pull Requests,,, guix-cookbook, GNU Guix Cookbook} for |
| 1862 | a suggested workflow on resolving merge conflicts. |
| 1863 | |
| 1864 | @node Elm Packages |
| 1865 | @subsection Elm Packages |
| 1866 | |
| 1867 | @cindex Elm |
| 1868 | Elm applications can be named like other software: their names need not |
| 1869 | mention Elm. |
| 1870 | |
| 1871 | Packages in the Elm sense (see @code{elm-build-system} under @ref{Build |
| 1872 | Systems}) are required use names of the format |
| 1873 | @var{author}@code{/}@var{project}, where both the @var{author} and the |
| 1874 | @var{project} may contain hyphens internally, and the @var{author} sometimes |
| 1875 | contains uppercase letters. |
| 1876 | |
| 1877 | To form the Guix package name from the upstream name, we follow a convention |
| 1878 | similar to Python packages (@pxref{Python Modules}), adding an @code{elm-} |
| 1879 | prefix unless the name would already begin with @code{elm-}. |
| 1880 | |
| 1881 | In many cases we can reconstruct an Elm package's upstream name heuristically, |
| 1882 | but, since conversion to a Guix-style name involves a loss of information, |
| 1883 | this is not always possible. Care should be taken to add the |
| 1884 | @code{'upstream-name} property when necessary so that @samp{guix import elm} |
| 1885 | will work correctly (@pxref{Invoking guix import}). The most notable scenarios |
| 1886 | when explicitly specifying the upstream name is necessary are: |
| 1887 | |
| 1888 | @enumerate |
| 1889 | @item |
| 1890 | When the @var{author} is @code{elm} and the @var{project} contains one or more |
| 1891 | hyphens, as with @code{elm/virtual-dom}; and |
| 1892 | |
| 1893 | @item |
| 1894 | When the @var{author} contains hyphens or uppercase letters, as with |
| 1895 | @code{Elm-Canvas/raster-shapes}---unless the @var{author} is |
| 1896 | @code{elm-explorations}, which is handled as a special case, so packages like |
| 1897 | @code{elm-explorations/markdown} do @emph{not} need to use the |
| 1898 | @code{'upstream-name} property. |
| 1899 | @end enumerate |
| 1900 | |
| 1901 | The module @code{(guix build-system elm)} provides the following utilities for |
| 1902 | working with names and related conventions: |
| 1903 | |
| 1904 | @deffn {Procedure} elm-package-origin @var{elm-name} @var{version} @ |
| 1905 | @var{hash} |
| 1906 | Returns a Git origin using the repository naming and tagging regime required |
| 1907 | for a published Elm package with the upstream name @var{elm-name} at version |
| 1908 | @var{version} with sha256 checksum @var{hash}. |
| 1909 | |
| 1910 | For example: |
| 1911 | @lisp |
| 1912 | (package |
| 1913 | (name "elm-html") |
| 1914 | (version "1.0.0") |
| 1915 | (source |
| 1916 | (elm-package-origin |
| 1917 | "elm/html" |
| 1918 | version |
| 1919 | (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a"))) |
| 1920 | ...) |
| 1921 | @end lisp |
| 1922 | @end deffn |
| 1923 | |
| 1924 | @deffn {Procedure} elm->package-name @var{elm-name} |
| 1925 | Returns the Guix-style package name for an Elm package with upstream name |
| 1926 | @var{elm-name}. |
| 1927 | |
| 1928 | Note that there is more than one possible @var{elm-name} for which |
| 1929 | @code{elm->package-name} will produce a given result. |
| 1930 | @end deffn |
| 1931 | |
| 1932 | @deffn {Procedure} guix-package->elm-name @var{package} |
| 1933 | Given an Elm @var{package}, returns the possibly-inferred upstream name, or |
| 1934 | @code{#f} the upstream name is not specified via the @code{'upstream-name} |
| 1935 | property and can not be inferred by @code{infer-elm-package-name}. |
| 1936 | @end deffn |
| 1937 | |
| 1938 | @deffn {Procedure} infer-elm-package-name @var{guix-name} |
| 1939 | Given the @var{guix-name} of an Elm package, returns the inferred upstream |
| 1940 | name, or @code{#f} if the upstream name can't be inferred. If the result is |
| 1941 | not @code{#f}, supplying it to @code{elm->package-name} would produce |
| 1942 | @var{guix-name}. |
| 1943 | @end deffn |
| 1944 | |
| 1945 | @node Fonts |
| 1946 | @subsection Fonts |
| 1947 | |
| 1948 | @cindex fonts |
| 1949 | For fonts that are in general not installed by a user for typesetting |
| 1950 | purposes, or that are distributed as part of a larger software package, |
| 1951 | we rely on the general packaging rules for software; for instance, this |
| 1952 | applies to the fonts delivered as part of the X.Org system or fonts that |
| 1953 | are part of TeX Live. |
| 1954 | |
| 1955 | To make it easier for a user to search for fonts, names for other packages |
| 1956 | containing only fonts are constructed as follows, independently of the |
| 1957 | upstream package name. |
| 1958 | |
| 1959 | The name of a package containing only one font family starts with |
| 1960 | @code{font-}; it is followed by the foundry name and a dash @code{-} |
| 1961 | if the foundry is known, and the font family name, in which spaces are |
| 1962 | replaced by dashes (and as usual, all upper case letters are transformed |
| 1963 | to lower case). |
| 1964 | For example, the Gentium font family by SIL is packaged under the name |
| 1965 | @code{font-sil-gentium}. |
| 1966 | |
| 1967 | For a package containing several font families, the name of the collection |
| 1968 | is used in the place of the font family name. |
| 1969 | For instance, the Liberation fonts consist of three families, |
| 1970 | Liberation Sans, Liberation Serif and Liberation Mono. |
| 1971 | These could be packaged separately under the names |
| 1972 | @code{font-liberation-sans} and so on; but as they are distributed together |
| 1973 | under a common name, we prefer to package them together as |
| 1974 | @code{font-liberation}. |
| 1975 | |
| 1976 | In the case where several formats of the same font family or font collection |
| 1977 | are packaged separately, a short form of the format, prepended by a dash, |
| 1978 | is added to the package name. We use @code{-ttf} for TrueType fonts, |
| 1979 | @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 |
| 1980 | fonts. |
| 1981 | |
| 1982 | |
| 1983 | @node Coding Style |
| 1984 | @section Coding Style |
| 1985 | |
| 1986 | In general our code follows the GNU Coding Standards (@pxref{Top,,, |
| 1987 | standards, GNU Coding Standards}). However, they do not say much about |
| 1988 | Scheme, so here are some additional rules. |
| 1989 | |
| 1990 | @menu |
| 1991 | * Programming Paradigm:: How to compose your elements. |
| 1992 | * Modules:: Where to store your code? |
| 1993 | * Data Types and Pattern Matching:: Implementing data structures. |
| 1994 | * Formatting Code:: Writing conventions. |
| 1995 | @end menu |
| 1996 | |
| 1997 | @node Programming Paradigm |
| 1998 | @subsection Programming Paradigm |
| 1999 | |
| 2000 | Scheme code in Guix is written in a purely functional style. One |
| 2001 | exception is code that involves input/output, and procedures that |
| 2002 | implement low-level concepts, such as the @code{memoize} procedure. |
| 2003 | |
| 2004 | @node Modules |
| 2005 | @subsection Modules |
| 2006 | @cindex build-side modules |
| 2007 | @cindex host-side modules |
| 2008 | Guile modules that are meant to be used on the builder side must live in |
| 2009 | the @code{(guix build @dots{})} name space. They must not refer to |
| 2010 | other Guix or GNU modules. However, it is OK for a ``host-side'' module |
| 2011 | to use a build-side module. As an example, the @code{(guix |
| 2012 | search-paths)} module should not be imported and used by a package since |
| 2013 | it isn't meant to be used as a ``build-side'' module. It would also |
| 2014 | couple the module with the package's dependency graph, which is |
| 2015 | undesirable. |
| 2016 | |
| 2017 | Modules that deal with the broader GNU system should be in the |
| 2018 | @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}. |
| 2019 | |
| 2020 | @node Data Types and Pattern Matching |
| 2021 | @subsection Data Types and Pattern Matching |
| 2022 | |
| 2023 | The tendency in classical Lisp is to use lists to represent everything, |
| 2024 | and then to browse them ``by hand'' using @code{car}, @code{cdr}, |
| 2025 | @code{cadr}, and co. There are several problems with that style, |
| 2026 | notably the fact that it is hard to read, error-prone, and a hindrance |
| 2027 | to proper type error reports. |
| 2028 | |
| 2029 | @findex define-record-type* |
| 2030 | @findex match-record |
| 2031 | @cindex pattern matching |
| 2032 | Guix code should define appropriate data types (for instance, using |
| 2033 | @code{define-record-type*}) rather than abuse lists. In addition, it |
| 2034 | should use pattern matching, via Guile’s @code{(ice-9 match)} module, |
| 2035 | especially when matching lists (@pxref{Pattern Matching,,, guile, GNU |
| 2036 | Guile Reference Manual}); pattern matching for records is better done |
| 2037 | using @code{match-record} from @code{(guix records)}, which, unlike |
| 2038 | @code{match}, verifies field names at macro-expansion time. |
| 2039 | |
| 2040 | When defining a new record type, keep the @dfn{record type descriptor} |
| 2041 | (RTD) private (@pxref{Records,,, guile, GNU Guile Reference Manual}, for |
| 2042 | more on records and RTDs). As an example, the @code{(guix packages)} |
| 2043 | module defines @code{<package>} as the RTD for package records but it |
| 2044 | does not export it; instead, it exports a type predicate, a constructor, |
| 2045 | and field accessors. Exporting RTDs would make it harder to change the |
| 2046 | application binary interface (because code in other modules might be |
| 2047 | matching fields by position) and would make it trivial for users to |
| 2048 | forge records of that type, bypassing any checks we may have in the |
| 2049 | official constructor (such as ``field sanitizers''). |
| 2050 | |
| 2051 | @node Formatting Code |
| 2052 | @subsection Formatting Code |
| 2053 | |
| 2054 | @cindex formatting code |
| 2055 | @cindex coding style |
| 2056 | When writing Scheme code, we follow common wisdom among Scheme |
| 2057 | programmers. In general, we follow the |
| 2058 | @url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp |
| 2059 | Style Rules}. This document happens to describe the conventions mostly |
| 2060 | used in Guile’s code too. It is very thoughtful and well written, so |
| 2061 | please do read it. |
| 2062 | |
| 2063 | Some special forms introduced in Guix, such as the @code{substitute*} |
| 2064 | macro, have special indentation rules. These are defined in the |
| 2065 | @file{.dir-locals.el} file, which Emacs automatically uses. Also note |
| 2066 | that Emacs-Guix provides @code{guix-devel-mode} mode that indents and |
| 2067 | highlights Guix code properly (@pxref{Development,,, emacs-guix, The |
| 2068 | Emacs-Guix Reference Manual}). |
| 2069 | |
| 2070 | @cindex indentation, of code |
| 2071 | @cindex formatting, of code |
| 2072 | If you do not use Emacs, please make sure your editor knows these rules. |
| 2073 | To automatically indent a package definition, you can also run: |
| 2074 | |
| 2075 | @example |
| 2076 | ./pre-inst-env guix style @var{package} |
| 2077 | @end example |
| 2078 | |
| 2079 | @noindent |
| 2080 | @xref{Invoking guix style}, for more information. |
| 2081 | |
| 2082 | We require all top-level procedures to carry a docstring. This |
| 2083 | requirement can be relaxed for simple private procedures in the |
| 2084 | @code{(guix build @dots{})} name space, though. |
| 2085 | |
| 2086 | Procedures should not have more than four positional parameters. Use |
| 2087 | keyword parameters for procedures that take more than four parameters. |
| 2088 | |
| 2089 | |
| 2090 | @node Submitting Patches |
| 2091 | @section Submitting Patches |
| 2092 | |
| 2093 | @cindex pull requests |
| 2094 | @cindex patch submission |
| 2095 | Development is done using the Git distributed version control system. |
| 2096 | Thus, access to the repository is not strictly necessary. We welcome |
| 2097 | contributions as @dfn{pull requests} (PR) at |
| 2098 | @url{https://codeberg.org/guix/guix/pulls/}@footnote{Before January 1st, |
| 2099 | 2026, changes would be submitted by email to |
| 2100 | @email{guix-patches@@gnu.org} and could be |
| 2101 | @uref{https://issues.guix.gnu.org, browsed online}. In accordance with |
| 2102 | @uref{https://codeberg.org/guix/guix-consensus-documents/src/branch/main/002-codeberg.md, |
| 2103 | Guix Consensus Document 002}, this method is no longer supported.}. |
| 2104 | |
| 2105 | There are two ways to create a pull request: |
| 2106 | |
| 2107 | @itemize |
| 2108 | @item |
| 2109 | By creating a personal ``fork'' of @uref{https://codeberg.org/guix/guix, |
| 2110 | the repository}, creating a branch with your changes, and |
| 2111 | @uref{https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/, |
| 2112 | submitting a pull request for that branch}. |
| 2113 | |
| 2114 | @item |
| 2115 | @cindex AGit workflow, for pull requests |
| 2116 | By following the @uref{https://forgejo.org/docs/next/user/agit-support/, |
| 2117 | @dfn{AGit workflow}}, which is somewhat more convenient and consumes |
| 2118 | less disk space at Codeberg since it removes the need to create a |
| 2119 | ``fork''. |
| 2120 | |
| 2121 | Assuming your local checkout is on the branch containing the changes you |
| 2122 | would like to submit for inclusion in the @code{master} branch, run: |
| 2123 | |
| 2124 | @example |
| 2125 | git push origin HEAD:refs/for/master \ |
| 2126 | -o topic=@var{topic} \ |
| 2127 | -o title=@var{title} -o description=@var{description} |
| 2128 | @end example |
| 2129 | |
| 2130 | @var{topic} must be an identifier without whitespace, similar to a |
| 2131 | branch name; @var{title} and @var{description} are arbitrary text that |
| 2132 | can be omitted, in which case the message of the last commit on the |
| 2133 | branch fills that role. |
| 2134 | |
| 2135 | To send an update to an AGit pull request of yours, run: |
| 2136 | |
| 2137 | @example |
| 2138 | git push origin HEAD:refs/for/master \ |
| 2139 | -o topic=@var{topic} -o force-push=yes |
| 2140 | @end example |
| 2141 | |
| 2142 | Codeberg automatically figures out which pull request @var{topic} |
| 2143 | corresponds to and updates the associated branch. |
| 2144 | @end itemize |
| 2145 | |
| 2146 | Contributors are encouraged to take a moment to set some Git |
| 2147 | repository options (@pxref{Configuring Git}) first, which can improve |
| 2148 | the readability of patches. Seasoned Guix developers may also want to |
| 2149 | look at the section on commit access (@pxref{Commit Access}). |
| 2150 | |
| 2151 | Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, |
| 2152 | standards, GNU Coding Standards}); you can check the commit history for |
| 2153 | examples. |
| 2154 | |
| 2155 | You can help make the review process more efficient, and increase the |
| 2156 | chance that your patch will be reviewed quickly, by describing the |
| 2157 | context of your patch and the impact you expect it to have. For |
| 2158 | example, if your patch is fixing something that is broken, describe the |
| 2159 | problem and how your patch fixes it. Tell us how you have tested your |
| 2160 | patch. Will users of the code changed by your patch have to adjust |
| 2161 | their workflow at all? If so, tell us how. In general, try to imagine |
| 2162 | what questions a reviewer will ask, and answer those questions in |
| 2163 | advance. |
| 2164 | |
| 2165 | Before submitting a patch that adds or modifies a package definition, |
| 2166 | please run through this check list: |
| 2167 | |
| 2168 | @enumerate |
| 2169 | @item |
| 2170 | If the authors of the packaged software provide a cryptographic |
| 2171 | signature for the release tarball, make an effort to verify the |
| 2172 | authenticity of the archive. For a detached GPG signature file this |
| 2173 | would be done with the @code{gpg --verify} command. |
| 2174 | |
| 2175 | @item |
| 2176 | Take some time to provide an adequate synopsis and description for the |
| 2177 | package. @xref{Synopses and Descriptions}, for some guidelines. |
| 2178 | |
| 2179 | @item |
| 2180 | Run @command{guix lint @var{package}}, where @var{package} is the |
| 2181 | name of the new or modified package, and fix any errors it reports |
| 2182 | (@pxref{Invoking guix lint}). |
| 2183 | |
| 2184 | @item |
| 2185 | Run @command{guix style @var{package}} to format the new package definition |
| 2186 | according to the project's conventions (@pxref{Invoking guix style}). |
| 2187 | |
| 2188 | @item |
| 2189 | Make sure the package builds on your platform, using @command{guix build |
| 2190 | @var{package}}. Also build at least its direct dependents with |
| 2191 | @command{guix build --dependents=1 @var{package}} |
| 2192 | (@pxref{build-dependents, @command{guix build}}). |
| 2193 | |
| 2194 | @item |
| 2195 | We recommend you also try building the package on other supported |
| 2196 | platforms. As you may not have access to actual hardware platforms, we |
| 2197 | recommend using the @code{qemu-binfmt-service-type} to emulate them. In |
| 2198 | order to enable it, add the @code{virtualization} service module and the |
| 2199 | following service to the list of services in your @code{operating-system} |
| 2200 | configuration: |
| 2201 | |
| 2202 | @lisp |
| 2203 | (service qemu-binfmt-service-type |
| 2204 | (qemu-binfmt-configuration |
| 2205 | (platforms (lookup-qemu-platforms "arm" "aarch64")))) |
| 2206 | @end lisp |
| 2207 | |
| 2208 | Then reconfigure your system. |
| 2209 | |
| 2210 | You can then build packages for different platforms by specifying the |
| 2211 | @code{--system} option. For example, to build the "hello" package for |
| 2212 | the armhf or aarch64 architectures, you would run the following |
| 2213 | commands, respectively: |
| 2214 | @example |
| 2215 | guix build --system=armhf-linux --rounds=2 hello |
| 2216 | guix build --system=aarch64-linux --rounds=2 hello |
| 2217 | @end example |
| 2218 | |
| 2219 | @item |
| 2220 | @cindex bundling |
| 2221 | Make sure the package does not use bundled copies of software already |
| 2222 | available as separate packages. |
| 2223 | |
| 2224 | Sometimes, packages include copies of the source code of their |
| 2225 | dependencies as a convenience for users. However, as a distribution, we |
| 2226 | want to make sure that such packages end up using the copy we already |
| 2227 | have in the distribution, if there is one. This improves resource usage |
| 2228 | (the dependency is built and stored only once), and allows the |
| 2229 | distribution to make transverse changes such as applying security |
| 2230 | updates for a given software package in a single place and have them |
| 2231 | affect the whole system---something that bundled copies prevent. |
| 2232 | |
| 2233 | @item |
| 2234 | Take a look at the profile reported by @command{guix size} |
| 2235 | (@pxref{Invoking guix size}). This will allow you to notice references |
| 2236 | to other packages unwillingly retained. It may also help determine |
| 2237 | whether to split the package (@pxref{Packages with Multiple Outputs}), |
| 2238 | and which optional dependencies should be used. In particular, avoid |
| 2239 | adding @code{texlive} as a dependency: because of its extreme size, use |
| 2240 | @code{texlive-local-tree} procedure instead. |
| 2241 | |
| 2242 | @item |
| 2243 | Check that dependent packages (if applicable) are not affected by the |
| 2244 | change; @command{guix refresh --list-dependent @var{package}} will help you |
| 2245 | do that (@pxref{Invoking guix refresh}). |
| 2246 | |
| 2247 | @item |
| 2248 | @cindex determinism, of build processes |
| 2249 | @cindex reproducible builds, checking |
| 2250 | Check whether the package's build process is deterministic. This |
| 2251 | typically means checking whether an independent build of the package |
| 2252 | yields the exact same result that you obtained, bit for bit. |
| 2253 | |
| 2254 | A simple way to do that is by building the same package several times in |
| 2255 | a row on your machine (@pxref{Invoking guix build}): |
| 2256 | |
| 2257 | @example |
| 2258 | guix build --rounds=2 my-package |
| 2259 | @end example |
| 2260 | |
| 2261 | This is enough to catch a class of common non-determinism issues, such |
| 2262 | as timestamps or randomly-generated output in the build result. |
| 2263 | |
| 2264 | Another option is to use @command{guix challenge} (@pxref{Invoking guix |
| 2265 | challenge}). You may run it once the package has been committed and |
| 2266 | built by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same |
| 2267 | result as you did. Better yet: Find another machine that can build it |
| 2268 | and run @command{guix publish}. Since the remote build machine is |
| 2269 | likely different from yours, this can catch non-determinism issues |
| 2270 | related to the hardware---e.g., use of different instruction set |
| 2271 | extensions---or to the operating system kernel---e.g., reliance on |
| 2272 | @code{uname} or @file{/proc} files. |
| 2273 | |
| 2274 | @item |
| 2275 | When writing documentation, please use gender-neutral wording when |
| 2276 | referring to people, such as |
| 2277 | @uref{https://en.wikipedia.org/wiki/Singular_they, singular |
| 2278 | ``they''@comma{} ``their''@comma{} ``them''}, and so forth. |
| 2279 | |
| 2280 | @item |
| 2281 | Verify that your patch contains only one set of related changes. |
| 2282 | Bundling unrelated changes together makes reviewing harder and slower. |
| 2283 | |
| 2284 | Examples of unrelated changes include the addition of several packages, |
| 2285 | or a package update along with fixes to that package. |
| 2286 | |
| 2287 | @item |
| 2288 | Please follow our code formatting rules, possibly running |
| 2289 | @command{guix style} script to do that automatically for you |
| 2290 | (@pxref{Formatting Code}). |
| 2291 | |
| 2292 | @item |
| 2293 | When possible, use mirrors in the source URL (@pxref{Invoking guix download}). |
| 2294 | Use reliable URLs, not generated ones. For instance, GitHub archives are not |
| 2295 | necessarily identical from one generation to the next, so in this case it's |
| 2296 | often better to clone the repository. Don't use the @code{name} field in |
| 2297 | the URL: it is not very useful and if the name changes, the URL will probably |
| 2298 | be wrong. |
| 2299 | |
| 2300 | @item |
| 2301 | Check if Guix builds (@pxref{Building from Git}) and address the |
| 2302 | warnings, especially those about use of undefined symbols. |
| 2303 | |
| 2304 | @item |
| 2305 | Make sure your changes do not break Guix and simulate a @command{guix pull} |
| 2306 | with: |
| 2307 | @example |
| 2308 | guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master --disable-authentication |
| 2309 | @end example |
| 2310 | |
| 2311 | @end enumerate |
| 2312 | |
| 2313 | @menu |
| 2314 | * Configuring Git:: |
| 2315 | @end menu |
| 2316 | |
| 2317 | @node Configuring Git |
| 2318 | @subsection Configuring Git |
| 2319 | @cindex git configuration |
| 2320 | |
| 2321 | If you have not done so already, you may wish to set a name and email |
| 2322 | that will be associated with your commits (@pxref{telling git your name, |
| 2323 | , Telling Git your name, git, Git User Manual}). If you wish to use a |
| 2324 | different name or email just for commits in this repository, you can |
| 2325 | use @command{git config --local}, or edit @file{.git/config} in the |
| 2326 | repository instead of @file{~/.gitconfig}. |
| 2327 | |
| 2328 | Other important Git configuration will automatically be configured when |
| 2329 | building the project (@pxref{Building from Git}). |
| 2330 | |
| 2331 | @node Tracking Bugs and Changes |
| 2332 | @section Tracking Bugs and Changes |
| 2333 | |
| 2334 | This section describes how the Guix project tracks its bug reports, |
| 2335 | patch submissions and topic branches. |
| 2336 | |
| 2337 | @menu |
| 2338 | * The Issue Tracker:: The official bug and patch tracker. |
| 2339 | * Managing Patches and Branches:: How changes to Guix are managed. |
| 2340 | * Cuirass Build Notifications:: Be alerted of any breakage via RSS feeds. |
| 2341 | @end menu |
| 2342 | |
| 2343 | @node The Issue Tracker |
| 2344 | @subsection The Issue Tracker |
| 2345 | |
| 2346 | Bug reports (@dfn{issues}) and patch submissions (@dfn{pull requests}) |
| 2347 | are currently tracked at the @uref{https://codeberg.org/guix/guix, |
| 2348 | project's home at Codeberg}. |
| 2349 | |
| 2350 | @node Managing Patches and Branches |
| 2351 | @subsection Managing Patches and Branches |
| 2352 | @cindex branching strategy |
| 2353 | @cindex rebuild scheduling strategy |
| 2354 | |
| 2355 | @c TODO: Update when qa.guix is hooked up to Codeberg. |
| 2356 | Submitted patches are picked up and tested by the quality assurance |
| 2357 | service; the result of that testing eventually shows up on the dashboard |
| 2358 | at @indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where |
| 2359 | @var{ISSUE_NUMBER} is the number assigned by the issue tracker, |
| 2360 | currently Debbugs (work is in progress to support Codeberg pull |
| 2361 | requests). Leave time for a review, without committing anything. |
| 2362 | |
| 2363 | As an exception, some changes considered ``trivial'' or ``obvious'' may |
| 2364 | be pushed directly to the @code{master} branch. This includes changes |
| 2365 | to fix typos and reverting commits that caused immediate problems. This |
| 2366 | is subject to being adjusted, allowing individuals to commit directly on |
| 2367 | non-controversial changes on parts they’re familiar with. |
| 2368 | |
| 2369 | Changes which affect more than 300 dependent packages (@pxref{Invoking |
| 2370 | guix refresh}) should first be pushed to a topic branch other than |
| 2371 | @code{master}; the set of changes should be consistent---e.g., ``GNOME |
| 2372 | update'', ``NumPy update'', etc. This allows for testing: the branch |
| 2373 | will automatically show up at |
| 2374 | @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}}, with an |
| 2375 | indication of its build status on various platforms. |
| 2376 | |
| 2377 | @cindex feature branches, coordination |
| 2378 | To help coordinate the merging of branches, you must create a new |
| 2379 | guix-patches issue each time you create a branch (@pxref{The Issue |
| 2380 | Tracker}). The title of the issue requesting to merge a branch should |
| 2381 | have the following format: |
| 2382 | |
| 2383 | @cindex merge requests, template |
| 2384 | @example |
| 2385 | Request for merging "@var{name}" branch |
| 2386 | @end example |
| 2387 | |
| 2388 | The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such |
| 2389 | issues and lists the merge requests on its main page. The following |
| 2390 | points apply to managing these branches: |
| 2391 | |
| 2392 | @enumerate |
| 2393 | @item |
| 2394 | The commits on the branch should be a combination of the patches |
| 2395 | relevant to the branch. Patches not related to the topic of the branch |
| 2396 | should go elsewhere. |
| 2397 | |
| 2398 | @item |
| 2399 | Any changes that can be made on the master branch, should be made on the |
| 2400 | master branch. If a commit can be split to apply part of the changes on |
| 2401 | master, this is good to do. |
| 2402 | |
| 2403 | @item |
| 2404 | It should be possible to re-create the branch by starting from master |
| 2405 | and applying the relevant patches. |
| 2406 | |
| 2407 | @item |
| 2408 | Avoid merging master in to the branch. Prefer rebasing or re-creating |
| 2409 | the branch on top of an updated master revision. |
| 2410 | |
| 2411 | @item |
| 2412 | Minimise the changes on master that are missing on the branch prior to |
| 2413 | merging the branch in to master. This means that the state of the |
| 2414 | branch better reflects the state of master should the branch be merged. |
| 2415 | |
| 2416 | @item |
| 2417 | If you don't have commit access, create the ``Request for merging'' |
| 2418 | issue and request that someone creates the branch. Include a list of |
| 2419 | issues/patches to include on the branch. |
| 2420 | @end enumerate |
| 2421 | |
| 2422 | Normally branches will be merged in a ``first come, first merged'' |
| 2423 | manner, tracked through the guix-patches issues. If you agree on a |
| 2424 | different order with those involved, you can track this by updating |
| 2425 | which issues block@footnote{You can mark an issue as blocked by another |
| 2426 | by emailing @email{control@@debbugs.gnu.org} with the following line in |
| 2427 | the body of the email: @code{block XXXXX by YYYYY}. Where @code{XXXXX} |
| 2428 | is the number for the blocked issue, and @code{YYYYY} is the number for |
| 2429 | the issue blocking it.} which other issues. Therefore, to know which |
| 2430 | branch is at the front of the queue, look for the oldest issue, or the |
| 2431 | issue that isn't @dfn{blocked} by any other branch merges. An ordered |
| 2432 | list of branches with the open issues is available at |
| 2433 | @url{https://qa.guix.gnu.org}. |
| 2434 | |
| 2435 | Once a branch is at the front of the queue, wait until sufficient time |
| 2436 | has passed for the build farms to have processed the changes, and for |
| 2437 | the necessary testing to have happened. For example, you can check |
| 2438 | @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see |
| 2439 | information on some builds and substitute availability. |
| 2440 | |
| 2441 | Once the branch has been merged, the issue should be closed and the |
| 2442 | branch deleted. |
| 2443 | |
| 2444 | @cindex work-in-progress branches, wip |
| 2445 | @cindex wip branches |
| 2446 | Sometimes, a branch may be a work in progress, for example for larger |
| 2447 | efforts such as updating the GNOME desktop. In these cases, the branch |
| 2448 | name should reflect this by having the @samp{wip-} prefix. The QA |
| 2449 | infrastructure will avoid building work-in-progress branches, so that |
| 2450 | the available resources can be better focused on building the branches |
| 2451 | that are ready to be merged. When the branch is no longer a work in |
| 2452 | progress, it should be renamed, with the @samp{wip-} prefix removed, and |
| 2453 | only then should the merge requests be created, as documented earlier. |
| 2454 | |
| 2455 | @node Cuirass Build Notifications |
| 2456 | @subsection Cuirass Build Notifications |
| 2457 | |
| 2458 | @cindex build event notifications, RSS feed |
| 2459 | @cindex notifications, build events |
| 2460 | Cuirass includes @acronym{RSS, Really Simple Syndication} feeds as one |
| 2461 | of its features (@pxref{Notifications,,,cuirass}). Since |
| 2462 | @url{https://ci.guix.gnu.org/, Berlin} runs an instance of Cuirass, this |
| 2463 | feature can be used to keep track of recently broken or fixed packages |
| 2464 | caused by changes pushed to the Guix git repository. Any RSS client can |
| 2465 | be used. A good one, included with Emacs, is @xref{Gnus,,,gnus}. To |
| 2466 | register the feed, copy its URL, then from the main Gnus buffer, |
| 2467 | @samp{*Group*}, do the following: |
| 2468 | |
| 2469 | @cindex Gnus, configuration to read CI RSS feeds |
| 2470 | @cindex RSS feeds, Gnus configuration |
| 2471 | @example |
| 2472 | @kbd{G R} https://ci.guix.gnu.org/events/rss/?specification=master RET |
| 2473 | Guix CI - master RET Build events for specification master. RET |
| 2474 | @end example |
| 2475 | |
| 2476 | @noindent |
| 2477 | Then, back at the @samp{*Group*} buffer, press @kbd{s} to save the newly |
| 2478 | added RSS group. As for any other Gnus group, you can update its |
| 2479 | content by pressing the @kbd{g} key. You should now receive |
| 2480 | notifications that read like: |
| 2481 | |
| 2482 | @example |
| 2483 | . [ ?: Cuirass ] Build tree-sitter-meson.aarch64-linux on master is fixed. |
| 2484 | . [ ?: Cuirass ] Build rust-pbkdf2.aarch64-linux on master is fixed. |
| 2485 | . [ ?: Cuirass ] Build rust-pbkdf2.x86_64-linux on master is fixed. |
| 2486 | @end example |
| 2487 | |
| 2488 | @noindent |
| 2489 | where each RSS entry contains a link to the Cuirass build details page |
| 2490 | of the associated build. |
| 2491 | |
| 2492 | @node Teams |
| 2493 | @section Teams |
| 2494 | @cindex teams |
| 2495 | |
| 2496 | To organize work on Guix, including but not just development efforts, |
| 2497 | the project has a set of @dfn{teams}. Each team has its own focus and |
| 2498 | interests and is the primary contact point for questions and |
| 2499 | contributions in those areas. A team's primary mission is to coordinate |
| 2500 | and review the work of individuals in its scope (@pxref{Reviewing the |
| 2501 | Work of Others}); it can make decisions within its scope, in agreement |
| 2502 | with other teams whenever there is overlap or a close connection, and in |
| 2503 | accordance with other project rules such as seeking consensus |
| 2504 | (@pxref{Making Decisions}). |
| 2505 | |
| 2506 | As an example, the Python team is responsible for core Python packaging |
| 2507 | matters; it can decide to upgrade core Python packages in a dedicated |
| 2508 | @code{python-team} branch, in collaboration with any team whose scope is |
| 2509 | directly dependent on Python---e.g., the Science team---and following |
| 2510 | branching rules (@pxref{Managing Patches and Branches}). The |
| 2511 | Documentation team helps review changes to the documentation and can |
| 2512 | initiate overarching documentation changes. The Translations team |
| 2513 | organizes translation of Guix and its manual and coordinates efforts in |
| 2514 | that area. The Core team is responsible for the development of core |
| 2515 | functionality and interfaces of Guix; because of its central nature, |
| 2516 | some of its work may require soliciting input from the community at |
| 2517 | large and seeking consensus before enacting decisions that would affect |
| 2518 | the entire community. |
| 2519 | |
| 2520 | Teams are defined in the @file{etc/teams.scm} file in the Guix |
| 2521 | repository. The scope of each team is defined, when applicable, as a |
| 2522 | set of files or as a regular expression matching file names. |
| 2523 | |
| 2524 | @cindex team membership |
| 2525 | Anyone with interest in a team's domain and willing to contribute to its |
| 2526 | work can apply to become a member by contacting current members by |
| 2527 | email; commit access is not a precondition. Membership is formalized by |
| 2528 | adding the person's name and email address to @file{etc/teams.scm}. |
| 2529 | Members who have not been participating in the team's work for one year |
| 2530 | or more may be removed; they are free to reapply for membership later. |
| 2531 | |
| 2532 | @cindex team creation |
| 2533 | One or more people may propose the creation of a new team by reaching |
| 2534 | out to the community by email at @email{guix-devel@@gnu.org}, clarifying |
| 2535 | the intended scope and purpose. When consensus is reached on the |
| 2536 | creation of this team, someone with commit access formalizes its |
| 2537 | creation by adding it and its initial members to @file{etc/teams.scm}. |
| 2538 | |
| 2539 | To list existing teams, run the following command from a Guix checkout: |
| 2540 | |
| 2541 | @example |
| 2542 | $ ./etc/teams.scm list-teams |
| 2543 | id: mentors |
| 2544 | name: Mentors |
| 2545 | description: A group of mentors who chaperone contributions by newcomers. |
| 2546 | members: |
| 2547 | + Charlie Smith <charlie@@example.org> |
| 2548 | @dots{} |
| 2549 | @end example |
| 2550 | |
| 2551 | @cindex teams, on Codeberg |
| 2552 | To generate a @file{CODEOWNERS} file, which Forgejo---the software |
| 2553 | behind Codeberg---uses to determine which team or person should review |
| 2554 | changes to a given set of files, run: |
| 2555 | |
| 2556 | @example |
| 2557 | ./etc/teams.scm codeowners > CODEOWNERS |
| 2558 | @end example |
| 2559 | |
| 2560 | Teams defined in @file{etc/teams.scm} are reflected |
| 2561 | @uref{https://codeberg.org/guix/guix, on Codeberg}; the ``Owners'' team |
| 2562 | on Codeberg, whose members have administration privileges over |
| 2563 | @uref{https://codeberg.org/guix, the entire ``organization''}, is the |
| 2564 | only one missing from this file. To synchronize team changes with |
| 2565 | Codeberg, a member of the ``Owners'' team can run: |
| 2566 | |
| 2567 | @example |
| 2568 | ./etc/teams.scm sync-codeberg-teams @var{token} |
| 2569 | @end example |
| 2570 | |
| 2571 | @noindent |
| 2572 | ... where @var{token} is a token created via the |
| 2573 | @url{https://codeberg.org/user/settings/applications, Codeberg |
| 2574 | applications settings page}, granting read/write access to the |
| 2575 | @samp{organization} permission. |
| 2576 | |
| 2577 | @node Making Decisions |
| 2578 | @section Making Decisions |
| 2579 | |
| 2580 | @cindex decision making |
| 2581 | @cindex consensus seeking |
| 2582 | Every contribution to the project involves a form of decision making. |
| 2583 | It is expected from all contributors, and even more so from committers, |
| 2584 | to help build consensus and make decisions based on consensus. By using |
| 2585 | consensus, we are committed to finding solutions that everyone can live |
| 2586 | with. It implies that no decision is made against significant concerns |
| 2587 | and these concerns are actively resolved with proposals that work for |
| 2588 | everyone. |
| 2589 | |
| 2590 | A contributor (who may or may not have commit access) wishing to block |
| 2591 | a proposal bears a special responsibility for finding alternatives, |
| 2592 | proposing ideas/code or explain the rationale for the status quo to |
| 2593 | resolve the deadlock. To learn what consensus decision making means and |
| 2594 | understand its finer details, you are encouraged to read |
| 2595 | @url{https://www.seedsforchange.org.uk/consensus}. |
| 2596 | |
| 2597 | Day-to-day decision making, for instance discussions about pull requests |
| 2598 | (@pxref{Reviewing the Work of Others}), happens informally among |
| 2599 | interested parties such as contributors and members of the relevant |
| 2600 | teams (@pxref{Teams}). |
| 2601 | |
| 2602 | @cindex GCD, Guix Consensus Documents |
| 2603 | @cindex Guix Consensus Documents (GCD) |
| 2604 | Decisions that are expected to have an impact on most contributors |
| 2605 | and/or on the broader user community---e.g., changes to project-wide |
| 2606 | policies, to core functionality, and so on---are made following the |
| 2607 | @acronym{GCD, Guix Consensus Document} process. The process provides a |
| 2608 | framework to formalize proposals and draw attention to them, to leave |
| 2609 | time for interested parties to discuss them, and to collectively accept |
| 2610 | or withdraw them based on input from participating team members. It is |
| 2611 | defined in |
| 2612 | @uref{https://consensus.guix.gnu.org/gcd/001-gcd-process.html, |
| 2613 | GCD@tie{}001}. Past GCDs can be seen at |
| 2614 | @uref{https://consensus.guix.gnu.org}, and discussions take place at |
| 2615 | @uref{https://codeberg.org/guix/guix-consensus-documents}. |
| 2616 | |
| 2617 | @node Commit Access |
| 2618 | @section Commit Access |
| 2619 | |
| 2620 | @cindex commit access, for developers |
| 2621 | Everyone can contribute to Guix without having commit access |
| 2622 | (@pxref{Submitting Patches}). However, for frequent contributors, |
| 2623 | having write access to the repository can be convenient. As a rule of |
| 2624 | thumb, a contributor should have accumulated fifty (50) reviewed commits |
| 2625 | to be considered as a committer and have sustained their activity in the |
| 2626 | project for at least 6 months. This ensures enough interactions with |
| 2627 | the contributor, which is essential for mentoring and assessing whether |
| 2628 | they are ready to become a committer. Commit access should not be |
| 2629 | thought of as a ``badge of honor'' but rather as a responsibility a |
| 2630 | contributor is willing to take to help the project. |
| 2631 | |
| 2632 | Committers are in a position where they enact technical decisions. Such |
| 2633 | decisions must be made by @emph{actively building consensus} among |
| 2634 | interested parties and stakeholders. @xref{Making Decisions}, for more |
| 2635 | on that. |
| 2636 | |
| 2637 | The following sections explain how to get commit access, how to be ready |
| 2638 | to push commits, and the policies and community expectations for commits |
| 2639 | pushed upstream. |
| 2640 | |
| 2641 | @subsection Applying for Commit Access |
| 2642 | |
| 2643 | When you deem it necessary, consider applying for commit |
| 2644 | access by following these steps: |
| 2645 | |
| 2646 | @enumerate |
| 2647 | @item |
| 2648 | Find three committers who would vouch for you. Each of them should |
| 2649 | email a statement to @email{guix-maintainers@@gnu.org} (a private alias |
| 2650 | for the collective of maintainers), signed with their OpenPGP key. |
| 2651 | |
| 2652 | Committers are expected to have had some interactions with you as a |
| 2653 | contributor and to be able to judge whether you are sufficiently |
| 2654 | familiar with the project's practices. It is @emph{not} a judgment on |
| 2655 | the value of your work, so a refusal should rather be interpreted as |
| 2656 | ``let's try again later''. |
| 2657 | |
| 2658 | @item |
| 2659 | Send @email{guix-maintainers@@gnu.org} a message stating your intent, |
| 2660 | listing the three committers who support your application, signed with |
| 2661 | the OpenPGP key you will use to sign commits, and giving its fingerprint |
| 2662 | (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an |
| 2663 | introduction to public-key cryptography with GnuPG. |
| 2664 | |
| 2665 | @c See <https://sha-mbles.github.io/>. |
| 2666 | Set up GnuPG such that it never uses the SHA1 hash algorithm for digital |
| 2667 | signatures, which is known to be unsafe since 2019, for instance by |
| 2668 | adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG |
| 2669 | Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}): |
| 2670 | |
| 2671 | @example |
| 2672 | digest-algo sha512 |
| 2673 | @end example |
| 2674 | |
| 2675 | @item |
| 2676 | Maintainers ultimately decide whether to grant you commit access, |
| 2677 | usually following your referrals' recommendation. |
| 2678 | |
| 2679 | @item |
| 2680 | @cindex OpenPGP, signed commits |
| 2681 | If and once you've been given access, please send a message to |
| 2682 | @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key |
| 2683 | you will use to sign commits (do that before pushing your first commit). |
| 2684 | That way, everyone can notice and ensure you control that OpenPGP key. |
| 2685 | |
| 2686 | @quotation Important |
| 2687 | Before you can push for the first time, maintainers must: |
| 2688 | |
| 2689 | @enumerate |
| 2690 | @item |
| 2691 | add your OpenPGP key to the @code{keyring} branch; |
| 2692 | @item |
| 2693 | add your OpenPGP fingerprint to the @file{.guix-authorizations} file of |
| 2694 | the branch(es) you will commit to. |
| 2695 | @end enumerate |
| 2696 | @end quotation |
| 2697 | |
| 2698 | @item |
| 2699 | Make sure to read the rest of this section and... profit! |
| 2700 | @end enumerate |
| 2701 | |
| 2702 | @quotation Note |
| 2703 | Maintainers are happy to give commit access to people who have been |
| 2704 | contributing for some time and have a track record---don't be shy and |
| 2705 | don't underestimate your work! |
| 2706 | |
| 2707 | However, note that the project is working towards a more automated patch |
| 2708 | review and merging system, which, as a consequence, may lead us to have |
| 2709 | fewer people with commit access to the main repository. Stay tuned! |
| 2710 | @end quotation |
| 2711 | |
| 2712 | All commits that are pushed to the central repository on Codeberg must |
| 2713 | be signed with an OpenPGP key, and the public key should be uploaded to |
| 2714 | your user account on Codeberg and to public key servers, such as |
| 2715 | @code{keys.openpgp.org}. To configure Git to automatically sign |
| 2716 | commits, run: |
| 2717 | |
| 2718 | @example |
| 2719 | git config commit.gpgsign true |
| 2720 | |
| 2721 | # Substitute the fingerprint of your public PGP key. |
| 2722 | git config user.signingkey CABBA6EA1DC0FF33 |
| 2723 | @end example |
| 2724 | |
| 2725 | To check that commits are signed with correct key, use: |
| 2726 | |
| 2727 | @example |
| 2728 | guix git authenticate |
| 2729 | @end example |
| 2730 | |
| 2731 | @xref{Building from Git} for running the first authentication of a Guix |
| 2732 | checkout. |
| 2733 | |
| 2734 | To avoid accidentally pushing unsigned or signed with the wrong key |
| 2735 | commits to Codeberg, make sure to configure Git according to |
| 2736 | @xref{Configuring Git}. |
| 2737 | |
| 2738 | @subsection Commit Policy |
| 2739 | |
| 2740 | If you get commit access, please make sure to follow the policy below |
| 2741 | (discussions of the policy can take place on |
| 2742 | @email{guix-devel@@gnu.org}). |
| 2743 | |
| 2744 | Ensure you're aware of how the changes should be handled |
| 2745 | (@pxref{Managing Patches and Branches}) prior to being pushed to the |
| 2746 | repository, especially for the @code{master} branch. |
| 2747 | |
| 2748 | If you're committing and pushing your own changes, try and wait at least |
| 2749 | one week (two weeks for more significant changes, up to one month for |
| 2750 | changes such as removing a package---@pxref{package-removal-policy, |
| 2751 | Package Removal}) after you send them for review. After this, if no one |
| 2752 | else is available to review them and if you're confident about the |
| 2753 | changes, it's OK to commit. |
| 2754 | |
| 2755 | When pushing a commit on behalf of somebody else, please add a |
| 2756 | @code{Signed-off-by} line at the end of the commit log message---e.g., |
| 2757 | with @command{git am --signoff}. This improves tracking of who did |
| 2758 | what. |
| 2759 | |
| 2760 | When adding channel news entries (@pxref{Channels, Writing Channel |
| 2761 | News}), make sure they are well-formed by running the following command |
| 2762 | right before pushing: |
| 2763 | |
| 2764 | @example |
| 2765 | make check-channel-news |
| 2766 | @end example |
| 2767 | |
| 2768 | @subsection Addressing Issues |
| 2769 | |
| 2770 | Peer review (@pxref{Submitting Patches}) and tools such as |
| 2771 | @command{guix lint} (@pxref{Invoking guix lint}) and the test suite |
| 2772 | (@pxref{Running the Test Suite}) should catch issues before they are |
| 2773 | pushed. Yet, commits that ``break'' functionality might occasionally |
| 2774 | go through. When that happens, there are two priorities: mitigating |
| 2775 | the impact, and understanding what happened to reduce the chance of |
| 2776 | similar incidents in the future. The responsibility for both these |
| 2777 | things primarily lies with those involved, but like everything this is |
| 2778 | a group effort. |
| 2779 | |
| 2780 | Some issues can directly affect all users---for instance because they |
| 2781 | make @command{guix pull} fail or break core functionality, because they |
| 2782 | break major packages (at build time or run time), or because they |
| 2783 | introduce known security vulnerabilities. |
| 2784 | |
| 2785 | @cindex reverting commits |
| 2786 | The people involved in authoring, reviewing, and pushing such |
| 2787 | commit(s) should be at the forefront to mitigate their impact in a |
| 2788 | timely fashion: by pushing a followup commit to fix it (if possible), |
| 2789 | or by reverting it to leave time to come up with a proper fix, and by |
| 2790 | communicating with other developers about the problem. |
| 2791 | |
| 2792 | If these persons are unavailable to address the issue in time, other |
| 2793 | committers are entitled to revert the commit(s), explaining in the |
| 2794 | commit log and on the mailing list what the problem was, with the goal |
| 2795 | of leaving time to the original committer, reviewer(s), and author(s) |
| 2796 | to propose a way forward. |
| 2797 | |
| 2798 | Once the problem has been dealt with, it is the responsibility of |
| 2799 | those involved to make sure the situation is understood. If you are |
| 2800 | working to understand what happened, focus on gathering information |
| 2801 | and avoid assigning any blame. Do ask those involved to describe what |
| 2802 | happened, do not ask them to explain the situation---this would |
| 2803 | implicitly blame them, which is unhelpful. Accountability comes from |
| 2804 | a consensus about the problem, learning from it and improving |
| 2805 | processes so that it's less likely to reoccur. |
| 2806 | |
| 2807 | @subsubsection Reverting commits |
| 2808 | |
| 2809 | Like normal commits, the commit message should state why the changes are |
| 2810 | being made, which in this case would be why the commits are being |
| 2811 | reverted. |
| 2812 | |
| 2813 | If the changes are being reverted because they led to excessive number |
| 2814 | of packages being affected, then a decision should be made whether to |
| 2815 | allow the build farms to build the changes, or whether to avoid |
| 2816 | this. For the bordeaux build farm, commits can be ignored by adding them |
| 2817 | to the @code{ignore-commits} list in the |
| 2818 | @code{build-from-guix-data-service} record, found in the bayfront |
| 2819 | machine configuration. |
| 2820 | |
| 2821 | @subsection Commit Revocation |
| 2822 | |
| 2823 | In order to reduce the possibility of mistakes, committers will have |
| 2824 | their Codeberg account removed from the Guix Codeberg project and their |
| 2825 | key removed from @file{.guix-authorizations} after 12 months of |
| 2826 | inactivity; they can ask to regain commit access by emailing the |
| 2827 | maintainers, without going through the vouching process. |
| 2828 | |
| 2829 | Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the |
| 2830 | current list of maintainers. You can email them privately at |
| 2831 | @email{guix-maintainers@@gnu.org}.} may also revoke an individual's |
| 2832 | commit rights, as a last resort, if cooperation with the rest of the |
| 2833 | community has caused too much friction---even within the bounds of the |
| 2834 | project's code of conduct (@pxref{Contributing}). They would only do so |
| 2835 | after public or private discussion with the individual and a clear |
| 2836 | notice. Examples of behavior that hinders cooperation and could lead to |
| 2837 | such a decision include: |
| 2838 | |
| 2839 | @itemize |
| 2840 | @item repeated violation of the commit policy stated above; |
| 2841 | @item repeated failure to take peer criticism into account; |
| 2842 | @item breaching trust through a series of grave incidents. |
| 2843 | @end itemize |
| 2844 | |
| 2845 | When maintainers resort to such a decision, they notify developers on |
| 2846 | @email{guix-devel@@gnu.org}; inquiries may be sent to |
| 2847 | @email{guix-maintainers@@gnu.org}. Depending on the situation, the |
| 2848 | individual may still be welcome to contribute. |
| 2849 | |
| 2850 | @subsection Helping Out |
| 2851 | |
| 2852 | One last thing: the project keeps moving forward because committers not |
| 2853 | only push their own awesome changes, but also offer some of their time |
| 2854 | @emph{reviewing} and pushing other people's changes. As a committer, |
| 2855 | you're welcome to use your expertise and commit rights to help other |
| 2856 | contributors, too! |
| 2857 | |
| 2858 | @node Reviewing the Work of Others |
| 2859 | @section Reviewing the Work of Others |
| 2860 | |
| 2861 | Perhaps the biggest action you can do to help GNU Guix grow as a project |
| 2862 | is to review the work contributed by others. You do not need to be a |
| 2863 | committer to do so; applying, reading the source, building, linting and |
| 2864 | running other people's series and sharing your comments about your |
| 2865 | experience will give some confidence to committers. You must |
| 2866 | ensure the check list found in the @ref{Submitting Patches} section has |
| 2867 | been correctly followed. A reviewed patch series should give the best |
| 2868 | chances for the proposed change to be merged faster, so if a change you |
| 2869 | would like to see merged hasn't yet been reviewed, this is the most |
| 2870 | appropriate thing to do! If you would like to review changes in a |
| 2871 | specific area and to receive notifications for incoming patches relevant |
| 2872 | to that domain, consider joining the relevant team(s) (@pxref{Teams}). |
| 2873 | |
| 2874 | @cindex reviewing, guidelines |
| 2875 | Review comments should be unambiguous; be as clear and explicit as you |
| 2876 | can about what you think should be changed, ensuring the author can take |
| 2877 | action on it. Please try to keep the following guidelines in mind |
| 2878 | during review: |
| 2879 | |
| 2880 | @enumerate |
| 2881 | @item |
| 2882 | @emph{Be clear and explicit about changes you are suggesting}, ensuring |
| 2883 | the author can take action on it. In particular, it is a good idea to |
| 2884 | explicitly ask for new revisions when you want it. |
| 2885 | |
| 2886 | @item |
| 2887 | @emph{Remain focused: do not change the scope of the work being |
| 2888 | reviewed.} For example, if the contribution touches code that follows a |
| 2889 | pattern deemed unwieldy, it would be unfair to ask the submitter to fix |
| 2890 | all occurrences of that pattern in the code; to put it simply, if a |
| 2891 | problem unrelated to the patch at hand was already there, do not ask the |
| 2892 | submitter to fix it. |
| 2893 | |
| 2894 | @item |
| 2895 | @emph{Ensure progress.} As they respond to review, submitters may |
| 2896 | submit new revisions of their changes; avoid requesting changes that you |
| 2897 | did not request in the previous round of comments. Overall, the |
| 2898 | submitter should get a clear sense of progress; the number of items open |
| 2899 | for discussion should clearly decrease over time. |
| 2900 | |
| 2901 | @item |
| 2902 | @emph{Aim for finalization.} Reviewing code is time-consuming. Your |
| 2903 | goal as a reviewer is to put the process on a clear path towards |
| 2904 | integration, possibly with agreed-upon changes, or rejection, with a |
| 2905 | clear and mutually-understood reasoning. Avoid leaving the review |
| 2906 | process in a lingering state with no clear way out. |
| 2907 | |
| 2908 | @item |
| 2909 | @emph{Review is a discussion.} The submitter's and reviewer's views on |
| 2910 | how to achieve a particular change may not always be aligned. To lead |
| 2911 | the discussion, remain focused, ensure progress and aim for |
| 2912 | finalization, spending time proportional to the stakes@footnote{The |
| 2913 | tendency to discuss minute details at length is often referred to as |
| 2914 | ``bikeshedding'', where much time is spent discussing each one's |
| 2915 | preference for the color of the shed at the expense of progress made on |
| 2916 | the project to keep bikes dry.}. As a reviewer, try hard to explain the |
| 2917 | rationale for suggestions you make, and to understand and take into |
| 2918 | account the submitter's motivation for doing things in a certain way. |
| 2919 | In other words, build consensus with everyone involved (@pxref{Making |
| 2920 | Decisions}). |
| 2921 | @end enumerate |
| 2922 | |
| 2923 | When you deem the proposed change adequate and ready for inclusion |
| 2924 | in Guix, you can explicitly say so for pull requests on Codeberg, for |
| 2925 | example by selecting ``Approve changes'' in the ``Finish review'' dialog |
| 2926 | of the web interface. |
| 2927 | |
| 2928 | @cindex LGTM, Looks Good To Me |
| 2929 | @cindex review tags |
| 2930 | @cindex Reviewed-by, git trailer |
| 2931 | The following well understood/codified |
| 2932 | @samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} |
| 2933 | @footnote{The @samp{Reviewed-by} Git trailer is used by other projects |
| 2934 | such as Linux, and is understood by third-party tools such as the |
| 2935 | @samp{b4 am} sub-command, which is able to retrieve the complete |
| 2936 | submission email thread from a public-inbox instance and add the Git |
| 2937 | trailers found in replies to the commit patches.} line should be used to |
| 2938 | sign off as a reviewer, meaning you have reviewed the change and that it |
| 2939 | looks good to you: |
| 2940 | |
| 2941 | @itemize |
| 2942 | @item |
| 2943 | If the @emph{whole} series (containing multiple commits) looks good to |
| 2944 | you, reply with |
| 2945 | @samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} |
| 2946 | to the cover page if it has one, or to the last patch of the series |
| 2947 | otherwise, adding another @samp{(for the whole series)} comment on the |
| 2948 | line below to explicit this fact. |
| 2949 | |
| 2950 | @item |
| 2951 | If you instead want to mark a @emph{single commit} as reviewed (but not |
| 2952 | the whole series), simply reply with |
| 2953 | @samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} |
| 2954 | to that commit message. |
| 2955 | @end itemize |
| 2956 | |
| 2957 | If you are not a committer, you can help others find a @emph{series} you |
| 2958 | have reviewed more easily by adding a @code{reviewed-looks-good} usertag |
| 2959 | for the @code{guix} user. |
| 2960 | |
| 2961 | @node Updating the Guix Package |
| 2962 | @section Updating the Guix Package |
| 2963 | |
| 2964 | @cindex update-guix-package, updating the guix package |
| 2965 | It is sometimes desirable to update the @code{guix} package itself (the |
| 2966 | package defined in @code{(gnu packages package-management)}), for |
| 2967 | example to make new daemon features available for use by the |
| 2968 | @code{guix-service-type} service type. In order to simplify this task, |
| 2969 | the following command can be used: |
| 2970 | |
| 2971 | @example |
| 2972 | make update-guix-package |
| 2973 | @end example |
| 2974 | |
| 2975 | The @code{update-guix-package} make target will use the last known |
| 2976 | @emph{commit} corresponding to @code{HEAD} in your Guix checkout, |
| 2977 | compute the hash of the Guix sources corresponding to that commit and |
| 2978 | update the @code{commit}, @code{revision} and hash of the @code{guix} |
| 2979 | package definition. |
| 2980 | |
| 2981 | To validate that the updated @code{guix} package hashes are correct and |
| 2982 | that it can be built successfully, the following command can be run from |
| 2983 | the directory of your Guix checkout: |
| 2984 | |
| 2985 | @example |
| 2986 | ./pre-inst-env guix build guix |
| 2987 | @end example |
| 2988 | |
| 2989 | To guard against accidentally updating the @code{guix} package to a |
| 2990 | commit that others can't refer to, a check is made that the commit used |
| 2991 | has already been pushed to the Codeberg-hosted Guix Git repository. |
| 2992 | |
| 2993 | This check can be disabled, @emph{at your own peril}, by setting the |
| 2994 | @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When |
| 2995 | this variable is set, the updated package source is also added to the |
| 2996 | store. This is used as part of the release process of Guix. |
| 2997 | |
| 2998 | @node Deprecation Policy |
| 2999 | @section Deprecation Policy |
| 3000 | |
| 3001 | @cindex deprecation policy |
| 3002 | As any lively project with a broad scope, Guix changes all the time and |
| 3003 | at all levels. Because it's user-extensible and programmable, |
| 3004 | incompatible changes can directly impact users and make their life |
| 3005 | harder. It is thus important to reduce user-visible incompatible |
| 3006 | changes to a minimum and, when such changes are deemed necessary, to |
| 3007 | clearly communicate them through a @dfn{deprecation period} so everyone |
| 3008 | can adapt with minimum hassle. This section defines the project's |
| 3009 | commitments for smooth deprecation and describes procedures and |
| 3010 | mechanisms to honor them. |
| 3011 | |
| 3012 | There are several ways to use Guix; how to handle deprecation will |
| 3013 | depend on each use case. Those can be roughly categorized like this: |
| 3014 | |
| 3015 | @itemize |
| 3016 | @item |
| 3017 | package management exclusively through the command line; |
| 3018 | |
| 3019 | @item |
| 3020 | advanced package management using the manifest and package interfaces; |
| 3021 | |
| 3022 | @item |
| 3023 | Home and System management, using the @code{operating-system} and/or |
| 3024 | @code{home-environment} interfaces together with the service interfaces; |
| 3025 | |
| 3026 | @item |
| 3027 | development or use of external tools that use programming interfaces |
| 3028 | such as the @code{(guix ...)} modules. |
| 3029 | @end itemize |
| 3030 | |
| 3031 | These use cases form a spectrum with varying degrees of coupling---from |
| 3032 | ``distant'' to tightly coupled. Based on this insight, we define the |
| 3033 | following @dfn{deprecation policies} that we consider suitable for each |
| 3034 | of these levels. |
| 3035 | |
| 3036 | @table @asis |
| 3037 | @item Command-line tools |
| 3038 | Guix sub-commands should be thought of as remaining available |
| 3039 | ``forever''. Once a Guix sub-command is to be removed, it should be |
| 3040 | deprecated first, and then remain available for @b{at least one year} |
| 3041 | after the first release that deprecated it. |
| 3042 | |
| 3043 | Deprecation should first be announced in the manual and as an entry in |
| 3044 | @file{etc/news.scm}; additional communication such as a blog post |
| 3045 | explaining the rationale is welcome. Months before the scheduled |
| 3046 | removal date, the command should print a warning explaining how to |
| 3047 | migrate. An example of this is the replacement of @command{guix |
| 3048 | environment} by @command{guix shell}, started in October |
| 3049 | 2021@footnote{For more details on the @command{guix shell} transition, |
| 3050 | see |
| 3051 | @uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}. |
| 3052 | |
| 3053 | Because of the broad impact of such a change, we recommend conducting a |
| 3054 | user survey before enacting a plan. |
| 3055 | |
| 3056 | @cindex package deprecation |
| 3057 | @item Package name changes |
| 3058 | When a package name changes, it must remain available under its old name |
| 3059 | for @b{at least six months}; the deprecation date should be stated in |
| 3060 | a comment in the code to ease the final removal. |
| 3061 | |
| 3062 | For example, @code{go-ipfs} was renamed to |
| 3063 | @code{kubo} following a decision made upstream; to communicate the name |
| 3064 | change to users, the package module provided this definition: |
| 3065 | |
| 3066 | @findex deprecated-package |
| 3067 | @findex define-deprecated-package |
| 3068 | @lisp |
| 3069 | (define-deprecated-package go-ipfs |
| 3070 | kubo) |
| 3071 | @end lisp |
| 3072 | |
| 3073 | That way, someone running @command{guix install go-ipfs} or similar sees |
| 3074 | a deprecation warning mentioning the new package name; likewise, someone |
| 3075 | referring to the @code{go-ipfs} @emph{variable} from their manifest or |
| 3076 | package definition will see a warning. |
| 3077 | |
| 3078 | Under the hood, @code{define-deprecated-package} combines |
| 3079 | @code{define-deprecated/public-alias} to mark the variable as deprecated |
| 3080 | (see below), and the @code{deprecated-package} procedure to mark the |
| 3081 | package name as deprecated. |
| 3082 | |
| 3083 | @cindex package removal policy |
| 3084 | @anchor{package-removal-policy} |
| 3085 | @item Package removal |
| 3086 | |
| 3087 | How packages may be removed depends on their build status and on their |
| 3088 | position in the package graph. |
| 3089 | @itemize |
| 3090 | @item Removal of packages that do not build |
| 3091 | |
| 3092 | A package that does not build becomes a removal candidate immediately. |
| 3093 | A pull request removing such a package should be filed on Codeberg |
| 3094 | with the @samp{deprecation} label. Additional justification for the |
| 3095 | (non-)importance, obsolescence etc. of the package is welcome, but not |
| 3096 | required. |
| 3097 | Such a pull request may be merged @b{at least three weeks} later if there |
| 3098 | is no opposition to the removal or if nobody has volunteered to repair the |
| 3099 | affected packages. |
| 3100 | |
| 3101 | @item Removal of building packages |
| 3102 | |
| 3103 | There are various reasons why packages may become removal candidates |
| 3104 | although they still build: For instance we may have a newer version of |
| 3105 | the same package in Guix, maintenance has stopped upstream, or the package |
| 3106 | is not adequately maintained in Guix. |
| 3107 | |
| 3108 | @table @asis |
| 3109 | @item Removal candidates that are building leaf packages |
| 3110 | Leaf packages may be removed following the above process, assuming that |
| 3111 | there is no opposition to the removal or that consensus for the removal |
| 3112 | has been reached. |
| 3113 | Leaf packages that are typically installed into user profiles (for |
| 3114 | instance applications, but also packages used in a service) should |
| 3115 | not be removed unless there are particularly good reasons, such as |
| 3116 | security implications. |
| 3117 | |
| 3118 | @item Removal candidates that are building packages with dependents |
| 3119 | Removing building packages on which other packages depend causes more |
| 3120 | disruption than removing leaf packages, since at the same time all |
| 3121 | dependent packages need to be removed. This may still be desirable for |
| 3122 | overarching reasons. For instance, we want to remove older versions of |
| 3123 | packages for which newer versions are already packaged, remove packages |
| 3124 | that are unmaintained or have reached end of life upstream, or that suffer |
| 3125 | from security vulnerabilities. |
| 3126 | |
| 3127 | In this case, the removal candidate may be removed together with all |
| 3128 | packages depending on it following the above procedure. If the removal |
| 3129 | candidate falls into the realm of a team, this team must be notified, |
| 3130 | and consensus shall be sought about the removal in particular with this |
| 3131 | team. Reasonable efforts shall be made beforehand to update or otherwise |
| 3132 | preserve dependent packages. |
| 3133 | |
| 3134 | @end table |
| 3135 | @end itemize |
| 3136 | |
| 3137 | @quotation Note |
| 3138 | Learn about pending package removals by checking |
| 3139 | @uref{https://codeberg.org/guix/guix/pulls?labels=445131, |
| 3140 | pull requests with the @samp{deprecation} label}. |
| 3141 | @end quotation |
| 3142 | |
| 3143 | @item Moving packages between modules |
| 3144 | |
| 3145 | When a package is moved from one module to another one, the corresponding |
| 3146 | variable @var{name} should be marked as deprecated in the old location |
| 3147 | for @b{at least six months}, for instance by adding |
| 3148 | @findex define-deprecated/public-alias |
| 3149 | @lisp |
| 3150 | (define-deprecated/public-alias @var{name} |
| 3151 | (@@ (gnu packages @var{new-module}) @var{name})) |
| 3152 | @end lisp |
| 3153 | in @var{gnu/packages/old-module.scm}. |
| 3154 | |
| 3155 | @item Package additions |
| 3156 | |
| 3157 | Packages submitted for inclusion must not fulfill the criteria to become |
| 3158 | a removal candidate immediately after addition. |
| 3159 | |
| 3160 | |
| 3161 | @cindex service deprecation |
| 3162 | @item Services |
| 3163 | Changes to services for Guix Home and Guix System have a direct impact |
| 3164 | on user configuration. For a user, adjusting to interface changes is |
| 3165 | rarely rewarding, which is why any such change must be clearly |
| 3166 | communicated in advance through deprecation warnings and documentation. |
| 3167 | |
| 3168 | Renaming of variables related to service, home, or system configuration |
| 3169 | must be communicated for at least six months before removal using the |
| 3170 | @code{(guix deprecation)} mechanisms. For example, renaming of |
| 3171 | @code{murmur-configuration} to @code{mumble-server-configuration} was |
| 3172 | communicated through a series of definitions like this one: |
| 3173 | |
| 3174 | @findex define-deprecated/public-alias |
| 3175 | @lisp |
| 3176 | (define-deprecated/public-alias |
| 3177 | murmur-configuration |
| 3178 | mumble-server-configuration) |
| 3179 | @end lisp |
| 3180 | |
| 3181 | Procedures slated for removal may be defined like this: |
| 3182 | |
| 3183 | @findex define-deprecated |
| 3184 | @lisp |
| 3185 | (define-deprecated (elogind-service #:key (config (elogind-configuration))) |
| 3186 | elogind-service-type |
| 3187 | (service elogind-service-type config)) |
| 3188 | @end lisp |
| 3189 | |
| 3190 | Record fields, notably fields of service configuration records, must |
| 3191 | follow a similar deprecation period. This is usually achieved through |
| 3192 | @i{ad hoc} means though. For example, the @code{hosts-file} field of |
| 3193 | @code{operating-system} was deprecated by adding a @code{sanitized} |
| 3194 | property that would emit a warning: |
| 3195 | |
| 3196 | @lisp |
| 3197 | (define-record-type* <operating-system> |
| 3198 | ;; @dots{} |
| 3199 | (hosts-file %operating-system-hosts-file ;deprecated |
| 3200 | (default #f) |
| 3201 | (sanitize warn-hosts-file-field-deprecation))) |
| 3202 | |
| 3203 | (define-deprecated (operating-system-hosts-file os) |
| 3204 | hosts-service-type |
| 3205 | (%operating-system-hosts-file os)) |
| 3206 | @end lisp |
| 3207 | |
| 3208 | When deprecating interfaces in @code{operating-system}, |
| 3209 | @code{home-environment}, @code{(gnu services)}, or any popular service, |
| 3210 | the deprecation must come with an entry in @code{etc/news.scm}. |
| 3211 | |
| 3212 | @cindex deprecation of programming interfaces |
| 3213 | @item Core interfaces |
| 3214 | Core programming interfaces, in particular the @code{(guix ...)} |
| 3215 | modules, may be relied on by a variety of external tools and channels. |
| 3216 | Any incompatible change must be formally deprecated with |
| 3217 | @code{define-deprecated}, as shown above, for @b{at least one year} |
| 3218 | before removal. The manual must clearly document the new interface and, |
| 3219 | except in obvious cases, explain how to migrate from the old one. |
| 3220 | |
| 3221 | As an example, the @code{build-expression->derivation} procedure was |
| 3222 | superseded by @code{gexp->derivation} and remained available as a |
| 3223 | deprecated symbol: |
| 3224 | |
| 3225 | @lisp |
| 3226 | (define-deprecated (build-expression->derivation store name exp |
| 3227 | #:key @dots{}) |
| 3228 | gexp->derivation |
| 3229 | @dots{}) |
| 3230 | @end lisp |
| 3231 | |
| 3232 | Sometimes bindings are moved from one module to another. In those |
| 3233 | cases, bindings must be reexported from the original module for at least |
| 3234 | one year. |
| 3235 | @end table |
| 3236 | |
| 3237 | This section does not cover all possible situations but hopefully allows |
| 3238 | users to know what to expect and developers to stick to its spirit. |
| 3239 | Please email @email{guix-devel@@gnu.org} for any questions. |
| 3240 | |
| 3241 | @cindex documentation |
| 3242 | @node Writing Documentation |
| 3243 | @section Writing Documentation |
| 3244 | |
| 3245 | Guix is documented using the Texinfo system. If you are not yet |
| 3246 | familiar with it, we accept contributions for documentation in most |
| 3247 | formats. That includes plain text, Markdown, Org, etc. |
| 3248 | |
| 3249 | Documentation contributions can be sent to |
| 3250 | @email{guix-patches@@gnu.org}. Prepend @samp{[DOCUMENTATION]} to the |
| 3251 | subject. |
| 3252 | |
| 3253 | When you need to make more than a simple addition to the documentation, |
| 3254 | we prefer that you send a proper patch as opposed to sending an email |
| 3255 | as described above. @xref{Submitting Patches} for more information on |
| 3256 | how to send your patches. |
| 3257 | |
| 3258 | To modify the documentation, you need to edit @file{doc/guix.texi} and |
| 3259 | @file{doc/contributing.texi} (which contains this documentation |
| 3260 | section), or @file{doc/guix-cookbook.texi} for the cookbook. If |
| 3261 | you compiled the Guix repository before, you will have |
| 3262 | many more @file{.texi} files that are translations of these |
| 3263 | documents. Do not modify them, the translation is managed through |
| 3264 | @uref{https://translate.codeberg.org/projects/guix, Weblate}. |
| 3265 | @xref{Translating Guix} for more information. |
| 3266 | |
| 3267 | To render documentation, you must first make sure that you ran |
| 3268 | @command{./configure} in your source tree (@pxref{Running Guix Before |
| 3269 | It Is Installed}). After that you can run one of the following |
| 3270 | commands: |
| 3271 | |
| 3272 | @itemize |
| 3273 | @item @samp{make doc/guix.info} to compile the Info manual. |
| 3274 | You can check it with @command{info doc/guix.info}. |
| 3275 | @item @samp{make doc/guix.html} to compile the HTML version. |
| 3276 | You can point your browser to the relevant file in the |
| 3277 | @file{doc/guix.html} directory. |
| 3278 | @item @samp{make doc/guix-cookbook.info} for the cookbook Info manual. |
| 3279 | @item @samp{make doc/guix-cookbook.html} for the cookbook HTML version. |
| 3280 | @end itemize |
| 3281 | |
| 3282 | @cindex translation |
| 3283 | @cindex l10n |
| 3284 | @cindex i18n |
| 3285 | @cindex native language support |
| 3286 | @node Translating Guix |
| 3287 | @section Translating Guix |
| 3288 | |
| 3289 | Writing code and packages is not the only way to provide a meaningful |
| 3290 | contribution to Guix. Translating to a language you speak is another |
| 3291 | example of a valuable contribution you can make. This section is designed |
| 3292 | to describe the translation process. It gives you advice on how you can |
| 3293 | get involved, what can be translated, what mistakes you should avoid and |
| 3294 | what we can do to help you! |
| 3295 | |
| 3296 | Guix is a big project that has multiple components that can be translated. |
| 3297 | We coordinate the translation effort on a |
| 3298 | @uref{https://translate.codeberg.org/projects/guix/,Weblate instance} |
| 3299 | hosted by Codeberg. You will need an account to submit translations. |
| 3300 | |
| 3301 | Some of the software packaged in Guix also contain translations. We do not |
| 3302 | host a translation platform for them. If you want to translate a package |
| 3303 | provided by Guix, you should contact their developers or find the information |
| 3304 | on their website. As an example, you can find the homepage of the |
| 3305 | @code{hello} package by typing @command{guix show hello}. On the ``homepage'' |
| 3306 | line, you will see @url{https://www.gnu.org/software/hello/} as the homepage. |
| 3307 | |
| 3308 | Many GNU and non-GNU packages can be translated on the |
| 3309 | @uref{https://translationproject.org,Translation Project}. Some projects |
| 3310 | with multiple components have their own platform. For instance, GNOME has |
| 3311 | its own platform, @uref{https://l10n.gnome.org/,Damned Lies}. |
| 3312 | |
| 3313 | Guix has five components hosted on Weblate. |
| 3314 | |
| 3315 | @itemize |
| 3316 | @item @code{guix} contains all the strings from the Guix software (the |
| 3317 | guided system installer, the package manager, etc), excluding packages. |
| 3318 | @item @code{packages} contains the synopsis (single-sentence description |
| 3319 | of a package) and description (longer description) of packages in Guix. |
| 3320 | @item @code{website} contains the official Guix website, except for |
| 3321 | blog posts and multimedia content. |
| 3322 | @item @code{documentation-manual} corresponds to this manual. |
| 3323 | @item @code{documentation-cookbook} is the component for the cookbook. |
| 3324 | @end itemize |
| 3325 | |
| 3326 | @subsubheading General Directions |
| 3327 | |
| 3328 | Once you get an account, you should be able to select a component from |
| 3329 | @uref{https://translate.codeberg.org/projects/guix/,the guix project}, |
| 3330 | and select a language. If your language does not appear in the list, go |
| 3331 | to the bottom and click on the ``Start new translation'' button. Select |
| 3332 | the language you want to translate to from the list, to start your new |
| 3333 | translation. |
| 3334 | |
| 3335 | Like lots of other free software packages, Guix uses |
| 3336 | @uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations, |
| 3337 | with which translatable strings are extracted from the source code to so-called |
| 3338 | PO files. |
| 3339 | |
| 3340 | Even though PO files are text files, changes should not be made with a text |
| 3341 | editor but with PO editing software. Weblate integrates PO editing |
| 3342 | functionality. Alternatively, translators can use any of various |
| 3343 | free-software tools for filling in translations, of which |
| 3344 | @uref{https://poedit.net/,Poedit} is one example, and (after logging in) |
| 3345 | @uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed |
| 3346 | file. There is also a special |
| 3347 | @uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU |
| 3348 | Emacs. Over time translators find out what software they are happy with and |
| 3349 | what features they need. |
| 3350 | |
| 3351 | On Weblate, you will find various links to the editor, that will show various |
| 3352 | subsets (or all) of the strings. Have a look around and at the |
| 3353 | @uref{https://docs.weblate.org/en/latest/,documentation} to familiarize |
| 3354 | yourself with the platform. |
| 3355 | |
| 3356 | @subsubheading Translation Components |
| 3357 | |
| 3358 | In this section, we provide more detailed guidance on the translation |
| 3359 | process, as well as details on what you should or should not do. When in |
| 3360 | doubt, please contact us, we will be happy to help! |
| 3361 | |
| 3362 | @table @asis |
| 3363 | @item guix |
| 3364 | Guix is written in the Guile programming language, and some strings contain |
| 3365 | special formatting that is interpreted by Guile. These special formatting |
| 3366 | should be highlighted by Weblate. They start with @code{~} followed by one |
| 3367 | or more characters. |
| 3368 | |
| 3369 | When printing the string, Guile replaces the special formatting symbols with |
| 3370 | actual values. For instance, the string @samp{ambiguous package specification |
| 3371 | `~a'} would be substituted to contain said package specification instead of |
| 3372 | @code{~a}. To properly translate this string, you must keep the formatting |
| 3373 | code in your translation, although you can place it where it makes sense in |
| 3374 | your language. For instance, the French translation says @samp{spécification |
| 3375 | du paquet « ~a » ambiguë} because the adjective needs to be placed in the |
| 3376 | end of the sentence. |
| 3377 | |
| 3378 | If there are multiple formatting symbols, make sure to respect the order. |
| 3379 | Guile does not know in which order you intended the string to be read, so it |
| 3380 | will substitute the symbols in the same order as the English sentence. |
| 3381 | |
| 3382 | As an example, you cannot translate @samp{package '~a' has been superseded by |
| 3383 | '~a'} by @samp{'~a' supersedes package '~a'}, because the meaning would be |
| 3384 | reversed. If @var{foo} is superseded by @var{bar}, the translation would read |
| 3385 | @samp{'foo' supersedes package 'bar'}. To work around this problem, it |
| 3386 | is possible to use more advanced formatting to select a given piece of data, |
| 3387 | instead of following the default English order. @xref{Formatted Output,,, |
| 3388 | guile, GNU Guile Reference Manual}, for more information on formatting in Guile. |
| 3389 | |
| 3390 | @item packages |
| 3391 | |
| 3392 | Package descriptions occasionally contain Texinfo markup (@pxref{Synopses |
| 3393 | and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}}, |
| 3394 | @samp{@@emph@{important@}}, etc. When translating, please leave markup as is. |
| 3395 | |
| 3396 | The characters after ``@@'' form the name of the markup, and the text between |
| 3397 | ``@{'' and ``@}'' is its content. In general, you should not translate the |
| 3398 | content of markup like @code{@@code}, as it contains literal code that do not |
| 3399 | change with language. You can translate the content of formatting markup such |
| 3400 | as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do |
| 3401 | not translate the name of the markup, or it will not be recognized. Do |
| 3402 | not translate the word after @code{@@end}, it is the name of the markup that |
| 3403 | is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}). |
| 3404 | |
| 3405 | @item documentation-manual and documentation-cookbook |
| 3406 | |
| 3407 | The first step to ensure a successful translation of the manual is to find |
| 3408 | and translate the following strings @emph{first}: |
| 3409 | |
| 3410 | @itemize |
| 3411 | @item @code{version.texi}: Translate this string as @code{version-xx.texi}, |
| 3412 | where @code{xx} is your language code (the one shown in the URL on |
| 3413 | weblate). |
| 3414 | @item @code{contributing.texi}: Translate this string as |
| 3415 | @code{contributing.xx.texi}, where @code{xx} is the same language code. |
| 3416 | @item @code{Top}: Do not translate this string, it is important for Texinfo. |
| 3417 | If you translate it, the document will be empty (missing a Top node). |
| 3418 | Please look for it, and register @code{Top} as its translation. |
| 3419 | @end itemize |
| 3420 | |
| 3421 | Translating these strings first ensure we can include your translation in |
| 3422 | the guix repository without breaking the make process or the |
| 3423 | @command{guix pull} machinery. |
| 3424 | |
| 3425 | The manual and the cookbook both use Texinfo. As for @code{packages}, please |
| 3426 | keep Texinfo markup as is. There are more possible markup types in the manual |
| 3427 | than in the package descriptions. In general, do not translate the content |
| 3428 | of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You |
| 3429 | should translate the content of formatting markup such as @code{@@emph}, |
| 3430 | @code{@@i}, etc. |
| 3431 | |
| 3432 | The manual contains sections that can be referred to by name by @code{@@ref}, |
| 3433 | @code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do |
| 3434 | not have to translate their content. If you keep the English title, we will |
| 3435 | automatically replace it with your translation of that title. This ensures |
| 3436 | that Texinfo will always be able to find the node. If you decide to change |
| 3437 | the translation of the title, the references will automatically be updated |
| 3438 | and you will not have to update them all yourself. |
| 3439 | |
| 3440 | When translating references from the cookbook to the manual, you need to |
| 3441 | replace the name of the manual and the name of the section. For instance, |
| 3442 | to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference |
| 3443 | Manual@}}, you would replace @code{Defining Packages} with the title of that |
| 3444 | section in the translated manual @emph{only} if that title is translated. |
| 3445 | If the title is not translated in your language yet, do not translate it here, |
| 3446 | or the link will be broken. Replace @code{guix} with @code{guix.xx} where |
| 3447 | @code{xx} is your language code. @code{GNU Guix Reference Manual} is the |
| 3448 | text of the link. You can translate it however you wish. |
| 3449 | |
| 3450 | @item website |
| 3451 | |
| 3452 | The website pages are written using SXML, an s-expression version of HTML, |
| 3453 | the basic language of the web. We have a process to extract translatable |
| 3454 | strings from the source, and replace complex s-expressions with a more familiar |
| 3455 | XML markup, where each markup is numbered. Translators can arbitrarily change |
| 3456 | the ordering, as in the following example. |
| 3457 | |
| 3458 | @example |
| 3459 | #. TRANSLATORS: Defining Packages is a section name |
| 3460 | #. in the English (en) manual. |
| 3461 | #: apps/base/templates/about.scm:64 |
| 3462 | msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules." |
| 3463 | msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>." |
| 3464 | @end example |
| 3465 | |
| 3466 | Note that you need to include the same markups. You cannot skip any. |
| 3467 | @end table |
| 3468 | |
| 3469 | In case you make a mistake, the component might fail to build properly with your |
| 3470 | language, or even make guix pull fail. To prevent that, we have a process |
| 3471 | in place to check the content of the files before pushing to our repository. |
| 3472 | We will not be able to update the translation for your language in Guix, so |
| 3473 | we will notify you (through weblate and/or by email) so you get a chance to |
| 3474 | fix the issue. |
| 3475 | |
| 3476 | @subsubheading Outside of Weblate |
| 3477 | |
| 3478 | Currently, some parts of Guix cannot be translated on Weblate, help wanted! |
| 3479 | |
| 3480 | @itemize |
| 3481 | @item @command{guix pull} news can be translated in @file{news.scm}, but is not |
| 3482 | available from Weblate. If you want to provide a translation, you |
| 3483 | can prepare a patch as described above, or simply send us your |
| 3484 | translation with the name of the news entry you translated and your |
| 3485 | language. @xref{Writing Channel News}, for more information about |
| 3486 | channel news. |
| 3487 | @item Guix blog posts cannot currently be translated. |
| 3488 | @item The installer script (for foreign distributions) is entirely in English. |
| 3489 | @item Some of the libraries Guix uses cannot be translated or are translated |
| 3490 | outside of the Guix project. Guile itself is not internationalized. |
| 3491 | @item Other manuals linked from this manual or the cookbook might not be |
| 3492 | translated. |
| 3493 | @end itemize |
| 3494 | |
| 3495 | @subsubheading Conditions for Inclusion |
| 3496 | |
| 3497 | There are no conditions for adding new translations of the @code{guix} and |
| 3498 | @code{guix-packages} components, other than they need at least one translated |
| 3499 | string. New languages will be added to Guix as soon as possible. The |
| 3500 | files may be removed if they fall out of sync and have no more translated |
| 3501 | strings. |
| 3502 | |
| 3503 | Given that the web site is dedicated to new users, we want its translation |
| 3504 | to be as complete as possible before we include it in the language menu. |
| 3505 | For a new language to be included, it needs to reach at least 80% completion. |
| 3506 | When a language is included, it may be removed in the future if it stays |
| 3507 | out of sync and falls below 60% completion. |
| 3508 | |
| 3509 | The manual and cookbook are automatically added in the default compilation |
| 3510 | target. Every time we synchronize translations, developers need to |
| 3511 | recompile all the translated manuals and cookbooks. This is useless for what |
| 3512 | is essentially the English manual or cookbook. Therefore, we will only |
| 3513 | include a new language when it reaches 10% completion in the component. |
| 3514 | When a language is included, it may be removed in the future if it stays |
| 3515 | out of sync and falls below 5% completion. |
| 3516 | |
| 3517 | @subsubheading Translation Infrastructure |
| 3518 | |
| 3519 | Weblate is backed by a git repository from which it discovers new strings to |
| 3520 | translate and pushes new and updated translations. Normally, it would be |
| 3521 | enough to give it commit access to our repositories. However, we decided |
| 3522 | to use a separate repository for two reasons. First, we would have to give |
| 3523 | Weblate commit access and authorize its signing key, but we do not trust it |
| 3524 | in the same way we trust guix developers, especially since we do not manage |
| 3525 | the instance ourselves. Second, if translators mess something up, it can |
| 3526 | break the generation of the website and/or guix pull for all our users, |
| 3527 | independently of their language. |
| 3528 | |
| 3529 | For these reasons, we use a dedicated repository to host translations, and we |
| 3530 | synchronize it with our guix and artworks repositories after checking no issue |
| 3531 | was introduced in the translation. |
| 3532 | |
| 3533 | Developers can download the latest PO files from weblate in the Guix |
| 3534 | repository by running the @command{make download-po} command. It will |
| 3535 | automatically download the latest files from weblate, reformat them to a |
| 3536 | canonical form, and check they do not contain issues. The manual needs to be |
| 3537 | built again to check for additional issues that might crash Texinfo. |
| 3538 | |
| 3539 | Before pushing new translation files, developers should add them to the |
| 3540 | make machinery so the translations are actually available. The process |
| 3541 | differs for the various components. |
| 3542 | |
| 3543 | @itemize |
| 3544 | @item New po files for the @code{guix} and @code{packages} components must |
| 3545 | be registered by adding the new language to @file{po/guix/LINGUAS} or |
| 3546 | @file{po/packages/LINGUAS}. |
| 3547 | @item New po files for the @code{documentation-manual} component must be |
| 3548 | registered by adding the file name to @code{DOC_PO_FILES} in |
| 3549 | @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to |
| 3550 | @code{info_TEXINFOS} in @file{doc/local.mk} and the generated |
| 3551 | @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to |
| 3552 | @code{TRANSLATED_INFO} also in @file{doc/local.mk}. |
| 3553 | @item New po files for the @code{documentation-cookbook} component must be |
| 3554 | registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in |
| 3555 | @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi} |
| 3556 | manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated |
| 3557 | @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also |
| 3558 | in @file{doc/local.mk}. |
| 3559 | @item New po files for the @code{website} component must be added to the |
| 3560 | @code{guix-artwork} repository, in @file{website/po/}. |
| 3561 | @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must |
| 3562 | be updated accordingly (see @file{website/i18n-howto.txt} for more |
| 3563 | information on the process). |
| 3564 | @end itemize |
| 3565 | |
| 3566 | |
| 3567 | @cindex infrastructure |
| 3568 | @node Contributing to Guix's Infrastructure |
| 3569 | @section Contributing to Guix's Infrastructure |
| 3570 | |
| 3571 | Since its inception, the Guix project has always valued its autonomy, and that |
| 3572 | reflects in its infrastructure: our servers run Guix System and exclusively |
| 3573 | free software, and are administered by volunteers. |
| 3574 | |
| 3575 | Of course this comes at a cost and this is why we need contributions. Our hope |
| 3576 | is to make infrastructure-related activity more legible so that maybe you can |
| 3577 | picture yourself helping in one of these areas. |
| 3578 | |
| 3579 | |
| 3580 | @menu |
| 3581 | * Coding:: |
| 3582 | * System Administration:: |
| 3583 | * Day-to-Day System Administration:: |
| 3584 | * On-Site Intervention:: |
| 3585 | * Hosting:: |
| 3586 | * Administrative Tasks:: |
| 3587 | @end menu |
| 3588 | |
| 3589 | @node Coding |
| 3590 | @subsection Coding |
| 3591 | |
| 3592 | The project runs many Guix-specific services; this is all lovely Scheme code |
| 3593 | but it tends to receive less attention than Guix itself: |
| 3594 | |
| 3595 | @itemize |
| 3596 | @item |
| 3597 | @url{https://git.cbaines.net/guix/bffe, Build Farm Front End} |
| 3598 | @item |
| 3599 | @url{https://codeberg.org/guix/cuirass/, Cuirass} |
| 3600 | @item |
| 3601 | @url{https://codeberg.org/guix/maintenance/src/branch/master/hydra/goggles.scm, |
| 3602 | Goggles} (IRC logger) |
| 3603 | @item |
| 3604 | @url{https://codeberg.org/guix/build-coordinator, Guix Build Coordinator} |
| 3605 | @item |
| 3606 | @url{https://codeberg.org/guix/data-service, Guix Data Service} |
| 3607 | @item |
| 3608 | @url{https://codeberg.org/luis-felipe/guix-packages-website, |
| 3609 | Guix Packages Website} |
| 3610 | @item |
| 3611 | @url{https://codeberg.org/guix/mumi, mumi} |
| 3612 | @item |
| 3613 | @url{https://codeberg.org/guix/nar-herder, Nar Herder} |
| 3614 | @item |
| 3615 | @url{https://codeberg.org/guix/qa-frontpage, QA Frontpage} |
| 3616 | @end itemize |
| 3617 | |
| 3618 | There is no time constraint on this coding activity: any improvement is |
| 3619 | welcome, whenever it comes. Most of these code bases are relatively small, |
| 3620 | which should make it easier to get started. |
| 3621 | |
| 3622 | Prerequisites: Familiarity with Guile, HTTP, and databases. |
| 3623 | |
| 3624 | If you wish to get started, check out the README of the project of your choice |
| 3625 | and get in touch with guix-devel and the primary developer(s) of the tool as |
| 3626 | per @code{git shortlog -s | sort -k1 -n}. |
| 3627 | |
| 3628 | @node System Administration |
| 3629 | @subsection System Administration |
| 3630 | |
| 3631 | Guix System configuration for all our systems is held in this repository: |
| 3632 | |
| 3633 | @url{https://codeberg.org/guix/maintenance.git/src/branch/master/hydra/} |
| 3634 | |
| 3635 | The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org) |
| 3636 | and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org, |
| 3637 | guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more). Both connect to a |
| 3638 | number of build machines and helpers. |
| 3639 | |
| 3640 | Without even having SSH access to the machine, you can help by posting patches |
| 3641 | to improve the configuration (you can test it with @code{guix system vm}). |
| 3642 | Here are ways you can help: |
| 3643 | |
| 3644 | @itemize |
| 3645 | @item |
| 3646 | Improve infra monitoring: set up a dashboard to monitor all the infrastructure, |
| 3647 | and an out-of-band channel to communicate about downtime. |
| 3648 | |
| 3649 | @item |
| 3650 | Implement web site redundancy: guix.gnu.org should be backed by several |
| 3651 | machines on different sites. Get in touch with us and/or send a patch! |
| 3652 | |
| 3653 | @item |
| 3654 | Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and |
| 3655 | ci.guix.gnu.org should be backed by several head nodes. |
| 3656 | |
| 3657 | @item |
| 3658 | Improve backup: there's currently ad-hoc backup of selected pieces over rsync |
| 3659 | between the two head nodes; we can improve on that, for example with a |
| 3660 | dedicated backup site and proper testing of recoverability. |
| 3661 | |
| 3662 | @item |
| 3663 | Support mirroring: We'd like to make it easy for others to mirror substitutes |
| 3664 | from ci.guix and bordeaux.guix, perhaps by offering public rsync access. |
| 3665 | |
| 3666 | @item |
| 3667 | Optimize our web services: Monitor the performance of our services and tweak |
| 3668 | nginx config or whatever it takes to improve it. |
| 3669 | |
| 3670 | There is no time constraint on this activity: any improvement is welcome, |
| 3671 | whenever you can work on it. |
| 3672 | |
| 3673 | Prerequisite: Familiarity with Guix System administration and ideally with the |
| 3674 | infrastructure handbook: |
| 3675 | |
| 3676 | @url{https://codeberg.org/guix/maintenance.git/src/branch/master/doc/infra-handbook.org, |
| 3677 | Infra-Handbook} |
| 3678 | |
| 3679 | @end itemize |
| 3680 | |
| 3681 | @node Day-to-Day System Administration |
| 3682 | @subsection Day-to-Day System Administration |
| 3683 | |
| 3684 | We're also looking for people who'd be willing to have SSH access to some of |
| 3685 | the infrastructure to help with day-to-day maintenance: restarting a build, |
| 3686 | restarting the occasional service that has gone wild (that can happen), |
| 3687 | reconfiguring/upgrading a machine, rebooting, etc. |
| 3688 | |
| 3689 | This day-to-day activity requires you to be available some of the time (during |
| 3690 | office hours or not, during the week-end or not), whenever is convenient for |
| 3691 | you, so you can react to issues reported on IRC, on the mailing list, or |
| 3692 | elsewhere, and synchronize with other sysadmins. |
| 3693 | |
| 3694 | Prerequisite: Being a ``known'' member of the community, familiarity with Guix |
| 3695 | System administration, with some of the services/web sites being run, and with |
| 3696 | the infrastructure handbook: |
| 3697 | |
| 3698 | @url{https://codeberg.org/guix/maintenance.git/src/branch/master/doc/infra-handbook.org, |
| 3699 | Infra-Handbook} |
| 3700 | |
| 3701 | @node On-Site Intervention |
| 3702 | @subsection On-Site Intervention |
| 3703 | |
| 3704 | The first front-end is currently generously hosted by the Max Delbrück Center |
| 3705 | (MDC), a research institute in Berlin, Germany. Only authorized personnel can |
| 3706 | physically access it. |
| 3707 | |
| 3708 | The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a |
| 3709 | professional data center shared with non-profit ISP Aquilenet. If you live in |
| 3710 | the region of Bordeaux and would like to help out when we need to go on-site, |
| 3711 | please make yourself known by emailing @email{guix-sysadmin@@gnu.org}. |
| 3712 | |
| 3713 | On-site interventions are rare, but they're usually in response to an |
| 3714 | emergency. |
| 3715 | |
| 3716 | @node Hosting |
| 3717 | @subsection Hosting |
| 3718 | |
| 3719 | We're looking for people who can host machines and help out whenever |
| 3720 | physical access is needed. More specifically: |
| 3721 | |
| 3722 | @itemize |
| 3723 | @item |
| 3724 | We need hosting of ``small'' machines such as single-board computers (AArch64, |
| 3725 | RISC-V) for use as build machines. |
| 3726 | |
| 3727 | @item |
| 3728 | We need hosting for front-ends and x86_64 build machines in a data center where |
| 3729 | they can be racked and where, ideally, several local Guix sysadmins can |
| 3730 | physically access them. |
| 3731 | @end itemize |
| 3732 | |
| 3733 | The machines should be accessible over Wireguard VPN most of the |
| 3734 | time, so longer power or network interruptions should be the |
| 3735 | exception. |
| 3736 | |
| 3737 | Prerequisites: Familiarity with installing and remotely administering Guix |
| 3738 | System. |
| 3739 | |
| 3740 | @node Administrative Tasks |
| 3741 | @subsection Administrative Tasks |
| 3742 | |
| 3743 | The infra remains up and running thanks to crucial administrative tasks, which |
| 3744 | includes: |
| 3745 | |
| 3746 | @itemize |
| 3747 | @item |
| 3748 | Selecting and purchasing hardware, for example build machines. |
| 3749 | @item |
| 3750 | Renewing domain names. |
| 3751 | |
| 3752 | @item |
| 3753 | Securing funding, in particular via the Guix Foundation: |
| 3754 | @url{https://foundation.guix.info, Guix Foundation} |
| 3755 | @end itemize |
| 3756 | |
| 3757 | Prerequisites: Familiarity with hardware, and/or DNS registrars, |
| 3758 | and/or sponsorship, and/or crowdfunding. |