guix - doc/contributing.texi

3761 lines · 149.3 KiB

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. Because there is no
1570	standardized way to run a test suite for Emacs packages, tests are
1571	disabled by default. When a test suite is available, it should be
1572	enabled by setting the @code{#:tests?} argument to @code{#true}. By
1573	default, the command to run the test is @command{make check}, but any
1574	command can be specified via the @code{#:test-command} argument. The
1575	@code{#:test-command} argument expects a list containing a command and
1576	its arguments, to be invoked during the @code{check} phase.
1577
1578	The Elisp dependencies of Emacs packages are typically provided as
1579	@code{propagated-inputs} when required at run time. As for other
1580	packages, build or test dependencies should be specified as
1581	@code{native-inputs}.
1582
1583	Emacs packages sometimes depend on resources directories that should be
1584	installed along the Elisp files. The @code{#:include} argument can be
1585	used for that purpose, by specifying a list of regexps to match. The
1586	best practice when using the @code{#:include} argument is to extend
1587	rather than override its default value (accessible via the
1588	@code{%default-include} variable). As an example, a yasnippet extension
1589	package typically include a @file{snippets} directory, which could be
1590	copied to the installation directory using:
1591
1592	@lisp
1593	#:include (cons "^snippets/" %default-include)
1594	@end lisp
1595
1596	When encountering problems, it is wise to check for the presence of the
1597	@code{Package-Requires} extension header in the package main source
1598	file, and whether any dependencies and their versions listed therein are
1599	satisfied.
1600
1601	@node Python Modules
1602	@subsection Python Modules
1603
1604	@cindex python
1605	The standard way to generate a package definition is to use
1606	@code{guix import pypi <name>}, where @var{name} is the name of the
1607	Python package on @url{https://pypi.org, PyPI}, see @pxref{Invoking guix
1608	import}. Please check with @code{guix lint <package-name>} that the
1609	generated package is valid.
1610
1611	To avoid confusion and naming clashes with other programming languages,
1612	Python module packages should be prefixed with @code{python-}.
1613
1614	If a project already contains the word @code{python}, please do not
1615	repeat it; for instance, the module python-dateutil is packaged under
1616	the name @code{python-dateutil}. If the project name starts with
1617	@code{py}, it is kept and prefixed as described above (e.g.@:
1618	@code{python-pytz}).
1619
1620	@quotation Note
1621	The standard build system for Python packages is Guix's implementation
1622	of the @url{https://peps.python.org/pep-0517/, formal Python standard}
1623	for specifying build requirements: @var{pyproject-build-system}.
1624	The @var{python-build-system} which corresponds to the way Python
1625	packages were built before PEP517, using the informally specified
1626	@file{setup.py} file, is now deprecated. @var{pyproject-build-system}
1627	will eventually be deprecated and renamed into
1628	@var{python-build-system} after its removal.
1629	@end quotation
1630
1631	@subsubsection Specifying Dependencies
1632	@cindex inputs, for Python packages
1633
1634	Dependency information for Python packages is usually available in the
1635	package source tree, with varying degrees of accuracy: in the
1636	@file{pyproject.toml} file, the @file{setup.py} file, in
1637	@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for
1638	test dependencies).
1639
1640	When editing a recipe for a Python package, the goal is to map these
1641	dependencies to the appropriate type of ``input'' (@pxref{package
1642	Reference, inputs}). Although the @code{pypi} importer normally does a
1643	good job (@pxref{Invoking guix import}), please verify the following
1644	check list to determine which dependency goes where.
1645
1646	@itemize
1647
1648	@item
1649	Python is packaged @emph{without} @code{setuptools} and @code{pip}
1650	installed per default.
1651
1652	@command{guix lint} will warn if @code{pip} or other unneeded
1653	native-inputs are added.
1654
1655	@item
1656	Python dependencies required at run time go into
1657	@code{propagated-inputs}. They are typically defined with the
1658	@code{install_requires} keyword in @file{setup.py}, or in the
1659	@file{requirements.txt} file.
1660
1661	@item
1662	Python packages required only at build time---e.g., those listed under
1663	@code{build-system.requires} in @file{pyproject.toml} or with the
1664	@code{setup_requires} keyword in @file{setup.py}---or dependencies only
1665	for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
1666	@code{native-inputs}. The rationale is that (1) they do not need to be
1667	propagated because they are not needed at run time, and (2) in a
1668	cross-compilation context, it's the target ``native'' input.
1669
1670	Examples are the @code{pytest}, @code{mock}, and @code{stestr} test
1671	frameworks. Of course if any of these packages is also required at
1672	run-time, it needs to go to @code{propagated-inputs}.
1673
1674	@item
1675	Anything that does not fall in the previous categories goes to
1676	@code{inputs}, for example programs or C libraries required for building
1677	Python packages containing C extensions.
1678
1679	@item
1680	If a Python package has optional dependencies (@code{extras_require}),
1681	it is up to you to decide whether to add them or not, based on their
1682	usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
1683	size}}).
1684
1685	@end itemize
1686
1687
1688	@node Perl Modules
1689	@subsection Perl Modules
1690
1691	@cindex perl
1692	Perl programs standing for themselves are named as any other package,
1693	using the lowercase upstream name.
1694	For Perl packages containing a single class, we use the lowercase class name,
1695	replace all occurrences of @code{::} by dashes and prepend the prefix
1696	@code{perl-}.
1697	So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
1698	Modules containing several classes keep their lowercase upstream name and
1699	are also prepended by @code{perl-}. Such modules tend to have the word
1700	@code{perl} somewhere in their name, which gets dropped in favor of the
1701	prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
1702
1703
1704	@node Java Packages
1705	@subsection Java Packages
1706
1707	@cindex java
1708	Java programs standing for themselves are named as any other package,
1709	using the lowercase upstream name.
1710
1711	To avoid confusion and naming clashes with other programming languages,
1712	it is desirable that the name of a package for a Java package is
1713	prefixed with @code{java-}. If a project already contains the word
1714	@code{java}, we drop this; for instance, the package @code{ngsjava} is
1715	packaged under the name @code{java-ngs}.
1716
1717	For Java packages containing a single class or a small class hierarchy,
1718	we use the lowercase class name, replace all occurrences of @code{.} by
1719	dashes and prepend the prefix @code{java-}. So the class
1720	@code{apache.commons.cli} becomes package
1721	@code{java-apache-commons-cli}.
1722
1723
1724	@node Rust Crates
1725	@subsection Rust Crates
1726
1727	@cindex rust
1728	Rust applications (binary crates) and libraries (library crates) are packaged
1729	separately. We put our main efforts into applications and only package
1730	libraries as sources, utilizing automation with a manual focus on unbundling
1731	vendored dependencies.
1732
1733	Rust applications are treated like any other package and named using the
1734	lowercase upstream name. When using the Cargo build system (@pxref{Build
1735	Systems, @code{cargo-build-system}}), Rust applications should have the
1736	@code{#:install-source?} parameter set to @code{#f}, as this parameter only
1737	makes sense for libraries. When the package source is a Cargo workspace,
1738	@code{#:cargo-install-paths} must be set to enable relevant support.
1739
1740	Rust libraries are hidden from the user interface and managed in two modules:
1741
1742	@table @code
1743	@item (gnu packages rust-crates)
1744	Source definitions imported from Rust packages' @file{Cargo.lock} via the
1745	@code{crate} importer (@pxref{Invoking guix import}).
1746
1747	Imported definitions must be checked and have vendored dependencies unbundled
1748	before being contributed to Guix.
1749
1750	@item (gnu packages rust-sources)
1751	More complex definitions that need to be full packages. This includes Rust
1752	libraries requiring external inputs to unbundle and Cargo workspaces.
1753
1754	These libraries should have the @code{#:skip-build?} parameter set to @code{#t}.
1755	For Cargo workspaces, @code{#:cargo-package-crates} must be set.
1756
1757	Since they are added manually, they follow the usual naming convention for Guix
1758	packages (@pxref{Package Naming}), with a @code{rust-} prefix.
1759
1760	In the Rust community it is common for multiple incompatible versions of a
1761	package to be used at any given time, so all libraries should have a versioned
1762	suffix. The versioned suffix is the left-most non-zero digit (and any leading
1763	zeros, of course). This follows the ``caret'' version scheme intended by Cargo.
1764	Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
1765
1766	In practice we often package development snapshots of Rust libraries and can't
1767	simply identify them by version. In this case, the complete version information
1768	can be turned into a version string via @code{git-version}, for example
1769	@code{rust-pipewire-0.8.0.fd3d8f7} and @code{rust-pubgrub-0.3.0.b70cf70}.
1770	@end table
1771
1772	When contributing Rust packages, we should have all modifications to these
1773	two modules, in the same commit as the package we are contributing.
1774
1775	To avoid merge conflicts with changes from multiple branches, these two modules
1776	are maintained by the Rust team (@pxref{Teams}).
1777
1778	Rust libraries are not referenced directly. @code{(guix build-sytem cargo)}
1779	provides a @code{cargo-inputs} procedure to lookup input lists generated by the
1780	lockfile importer.
1781
1782	@cindex cargo inputs
1783	@findex define-cargo-inputs
1784	@findex lookup-cargo-inputs
1785	@deffn {Procedure} cargo-inputs name [#:module '(gnu packages rust-crates)]
1786	Lookup Cargo inputs for @var{name} in @var{module}, return an empty list if
1787	unavailable.
1788
1789	@var{name} must be consistent with the one used in lockfile importer invocation,
1790	usually matching the variable name of the package:
1791
1792	@example
1793	$ guix import -i @file{gnu/packages/rust-crates.scm} crate -f @file{/path/to/Cargo.lock} @var{name}
1794	@end example
1795
1796	@var{module} must export a public interface @code{lookup-cargo-inputs}, a
1797	template is available in the @file{etc/teams/rust} directory of Guix source
1798	tree.
1799	@end deffn
1800
1801	@xref{Packaging Rust Crates,,, guix-cookbook, GNU Guix Cookbook}, for
1802	packaging workflow.
1803
1804	@subsubsection Commit messages
1805
1806	The commit message must have a general brief mention to entry changes
1807	in @code{(gnu packages rust-crates)}. For changes in @code{(gnu packages
1808	rust-sources)}, the commit message must explicitly mention all changes to the
1809	packages.
1810
1811	Here are some examples for different situations:
1812
1813	@itemize
1814
1815	@item
1816	Adding a new Rust package:
1817
1818	@example
1819	gnu: Add catppuccin-whiskers.
1820
1821	* gnu/packages/rust-apps.scm (catppuccin-whiskers): New variable.
1822	* gnu/packages/rust-crates.scm (lookup-cargo-inputs)
1823	[catppuccin-whiskers]: New entry.
1824	@end example
1825
1826	@item
1827	Updating a simple package:
1828
1829	@example
1830	gnu: watchexec: Update to 2.3.2.
1831
1832	* gnu/packages/rust-apps.scm (watchexec): Update to 2.3.2.
1833	* gnu/packages/rust-crates.scm (lookup-cargo-inputs)[watchexec]:
1834	Update entry.
1835	@end example
1836
1837	@item
1838	Updating a package with sources:
1839
1840	@example
1841	gnu: typst: Update to 0.14.0.
1842
1843	* gnu/packages/rust-apps.scm (typst): Update to 0.14.0.
1844	[arguments]<#:rust>: Use rust-1.88.
1845	* gnu/packages/rust-crates.scm (lookup-cargo-inputs)[typst]: Update
1846	entry.
1847	[rust-syntect-5]: Rename to rust-syntect-5.2.
1848	[rust-syntect-5.3]: New entry.
1849	* gnu/packages/rust-sources.scm (rust-hypher-0.1): Update to 0.1.6.
1850	(rust-syntect-5): Rename to rust-syntect-5.2.
1851	[inputs]: Rename cargo-inputs rust-syntect-5 to rust-syntect-5.2.
1852	(rust-syntect-5.3): New variable.
1853	@end example
1854
1855	@end itemize
1856
1857	@subsubsection Resolving merge conflicts in Pull Requests
1858
1859	For Rust crates, the recommended way to solve merge conflicts is to drop all
1860	changes to @code{gnu/packages/rust-crates.scm}, rebase onto the desired branch
1861	and run the lockfile importer again, manually adding back all relevant snippets
1862	(if any).
1863
1864	@xref{Common Workflow for Resolving Merge Conflicts on Existing Pull Requests,,, guix-cookbook, GNU Guix Cookbook} for
1865	a suggested workflow on resolving merge conflicts.
1866
1867	@node Elm Packages
1868	@subsection Elm Packages
1869
1870	@cindex Elm
1871	Elm applications can be named like other software: their names need not
1872	mention Elm.
1873
1874	Packages in the Elm sense (see @code{elm-build-system} under @ref{Build
1875	Systems}) are required use names of the format
1876	@var{author}@code{/}@var{project}, where both the @var{author} and the
1877	@var{project} may contain hyphens internally, and the @var{author} sometimes
1878	contains uppercase letters.
1879
1880	To form the Guix package name from the upstream name, we follow a convention
1881	similar to Python packages (@pxref{Python Modules}), adding an @code{elm-}
1882	prefix unless the name would already begin with @code{elm-}.
1883
1884	In many cases we can reconstruct an Elm package's upstream name heuristically,
1885	but, since conversion to a Guix-style name involves a loss of information,
1886	this is not always possible. Care should be taken to add the
1887	@code{'upstream-name} property when necessary so that @samp{guix import elm}
1888	will work correctly (@pxref{Invoking guix import}). The most notable scenarios
1889	when explicitly specifying the upstream name is necessary are:
1890
1891	@enumerate
1892	@item
1893	When the @var{author} is @code{elm} and the @var{project} contains one or more
1894	hyphens, as with @code{elm/virtual-dom}; and
1895
1896	@item
1897	When the @var{author} contains hyphens or uppercase letters, as with
1898	@code{Elm-Canvas/raster-shapes}---unless the @var{author} is
1899	@code{elm-explorations}, which is handled as a special case, so packages like
1900	@code{elm-explorations/markdown} do @emph{not} need to use the
1901	@code{'upstream-name} property.
1902	@end enumerate
1903
1904	The module @code{(guix build-system elm)} provides the following utilities for
1905	working with names and related conventions:
1906
1907	@deffn {Procedure} elm-package-origin @var{elm-name} @var{version} @
1908	@var{hash}
1909	Returns a Git origin using the repository naming and tagging regime required
1910	for a published Elm package with the upstream name @var{elm-name} at version
1911	@var{version} with sha256 checksum @var{hash}.
1912
1913	For example:
1914	@lisp
1915	(package
1916	(name "elm-html")
1917	(version "1.0.0")
1918	(source
1919	(elm-package-origin
1920	"elm/html"
1921	version
1922	(base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
1923	...)
1924	@end lisp
1925	@end deffn
1926
1927	@deffn {Procedure} elm->package-name @var{elm-name}
1928	Returns the Guix-style package name for an Elm package with upstream name
1929	@var{elm-name}.
1930
1931	Note that there is more than one possible @var{elm-name} for which
1932	@code{elm->package-name} will produce a given result.
1933	@end deffn
1934
1935	@deffn {Procedure} guix-package->elm-name @var{package}
1936	Given an Elm @var{package}, returns the possibly-inferred upstream name, or
1937	@code{#f} the upstream name is not specified via the @code{'upstream-name}
1938	property and can not be inferred by @code{infer-elm-package-name}.
1939	@end deffn
1940
1941	@deffn {Procedure} infer-elm-package-name @var{guix-name}
1942	Given the @var{guix-name} of an Elm package, returns the inferred upstream
1943	name, or @code{#f} if the upstream name can't be inferred. If the result is
1944	not @code{#f}, supplying it to @code{elm->package-name} would produce
1945	@var{guix-name}.
1946	@end deffn
1947
1948	@node Fonts
1949	@subsection Fonts
1950
1951	@cindex fonts
1952	For fonts that are in general not installed by a user for typesetting
1953	purposes, or that are distributed as part of a larger software package,
1954	we rely on the general packaging rules for software; for instance, this
1955	applies to the fonts delivered as part of the X.Org system or fonts that
1956	are part of TeX Live.
1957
1958	To make it easier for a user to search for fonts, names for other packages
1959	containing only fonts are constructed as follows, independently of the
1960	upstream package name.
1961
1962	The name of a package containing only one font family starts with
1963	@code{font-}; it is followed by the foundry name and a dash @code{-}
1964	if the foundry is known, and the font family name, in which spaces are
1965	replaced by dashes (and as usual, all upper case letters are transformed
1966	to lower case).
1967	For example, the Gentium font family by SIL is packaged under the name
1968	@code{font-sil-gentium}.
1969
1970	For a package containing several font families, the name of the collection
1971	is used in the place of the font family name.
1972	For instance, the Liberation fonts consist of three families,
1973	Liberation Sans, Liberation Serif and Liberation Mono.
1974	These could be packaged separately under the names
1975	@code{font-liberation-sans} and so on; but as they are distributed together
1976	under a common name, we prefer to package them together as
1977	@code{font-liberation}.
1978
1979	In the case where several formats of the same font family or font collection
1980	are packaged separately, a short form of the format, prepended by a dash,
1981	is added to the package name. We use @code{-ttf} for TrueType fonts,
1982	@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
1983	fonts.
1984
1985
1986	@node Coding Style
1987	@section Coding Style
1988
1989	In general our code follows the GNU Coding Standards (@pxref{Top,,,
1990	standards, GNU Coding Standards}). However, they do not say much about
1991	Scheme, so here are some additional rules.
1992
1993	@menu
1994	* Programming Paradigm:: How to compose your elements.
1995	* Modules:: Where to store your code?
1996	* Data Types and Pattern Matching:: Implementing data structures.
1997	* Formatting Code:: Writing conventions.
1998	@end menu
1999
2000	@node Programming Paradigm
2001	@subsection Programming Paradigm
2002
2003	Scheme code in Guix is written in a purely functional style. One
2004	exception is code that involves input/output, and procedures that
2005	implement low-level concepts, such as the @code{memoize} procedure.
2006
2007	@node Modules
2008	@subsection Modules
2009	@cindex build-side modules
2010	@cindex host-side modules
2011	Guile modules that are meant to be used on the builder side must live in
2012	the @code{(guix build @dots{})} name space. They must not refer to
2013	other Guix or GNU modules. However, it is OK for a ``host-side'' module
2014	to use a build-side module. As an example, the @code{(guix
2015	search-paths)} module should not be imported and used by a package since
2016	it isn't meant to be used as a ``build-side'' module. It would also
2017	couple the module with the package's dependency graph, which is
2018	undesirable.
2019
2020	Modules that deal with the broader GNU system should be in the
2021	@code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
2022
2023	@node Data Types and Pattern Matching
2024	@subsection Data Types and Pattern Matching
2025
2026	The tendency in classical Lisp is to use lists to represent everything,
2027	and then to browse them ``by hand'' using @code{car}, @code{cdr},
2028	@code{cadr}, and co. There are several problems with that style,
2029	notably the fact that it is hard to read, error-prone, and a hindrance
2030	to proper type error reports.
2031
2032	@findex define-record-type*
2033	@findex match-record
2034	@cindex pattern matching
2035	Guix code should define appropriate data types (for instance, using
2036	@code{define-record-type*}) rather than abuse lists. In addition, it
2037	should use pattern matching, via Guile’s @code{(ice-9 match)} module,
2038	especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
2039	Guile Reference Manual}); pattern matching for records is better done
2040	using @code{match-record} from @code{(guix records)}, which, unlike
2041	@code{match}, verifies field names at macro-expansion time.
2042
2043	When defining a new record type, keep the @dfn{record type descriptor}
2044	(RTD) private (@pxref{Records,,, guile, GNU Guile Reference Manual}, for
2045	more on records and RTDs). As an example, the @code{(guix packages)}
2046	module defines @code{<package>} as the RTD for package records but it
2047	does not export it; instead, it exports a type predicate, a constructor,
2048	and field accessors. Exporting RTDs would make it harder to change the
2049	application binary interface (because code in other modules might be
2050	matching fields by position) and would make it trivial for users to
2051	forge records of that type, bypassing any checks we may have in the
2052	official constructor (such as ``field sanitizers'').
2053
2054	@node Formatting Code
2055	@subsection Formatting Code
2056
2057	@cindex formatting code
2058	@cindex coding style
2059	When writing Scheme code, we follow common wisdom among Scheme
2060	programmers. In general, we follow the
2061	@url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
2062	Style Rules}. This document happens to describe the conventions mostly
2063	used in Guile’s code too. It is very thoughtful and well written, so
2064	please do read it.
2065
2066	Some special forms introduced in Guix, such as the @code{substitute*}
2067	macro, have special indentation rules. These are defined in the
2068	@file{.dir-locals.el} file, which Emacs automatically uses. Also note
2069	that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
2070	highlights Guix code properly (@pxref{Development,,, emacs-guix, The
2071	Emacs-Guix Reference Manual}).
2072
2073	@cindex indentation, of code
2074	@cindex formatting, of code
2075	If you do not use Emacs, please make sure your editor knows these rules.
2076	To automatically indent a package definition, you can also run:
2077
2078	@example
2079	./pre-inst-env guix style @var{package}
2080	@end example
2081
2082	@noindent
2083	@xref{Invoking guix style}, for more information.
2084
2085	We require all top-level procedures to carry a docstring. This
2086	requirement can be relaxed for simple private procedures in the
2087	@code{(guix build @dots{})} name space, though.
2088
2089	Procedures should not have more than four positional parameters. Use
2090	keyword parameters for procedures that take more than four parameters.
2091
2092
2093	@node Submitting Patches
2094	@section Submitting Patches
2095
2096	@cindex pull requests
2097	@cindex patch submission
2098	Development is done using the Git distributed version control system.
2099	Thus, access to the repository is not strictly necessary. We welcome
2100	contributions as @dfn{pull requests} (PR) at
2101	@url{https://codeberg.org/guix/guix/pulls/}@footnote{Before January 1st,
2102	2026, changes would be submitted by email to
2103	@email{guix-patches@@gnu.org} and could be
2104	@uref{https://issues.guix.gnu.org, browsed online}. In accordance with
2105	@uref{https://codeberg.org/guix/guix-consensus-documents/src/branch/main/002-codeberg.md,
2106	Guix Consensus Document 002}, this method is no longer supported.}.
2107
2108	There are two ways to create a pull request:
2109
2110	@itemize
2111	@item
2112	By creating a personal ``fork'' of @uref{https://codeberg.org/guix/guix,
2113	the repository}, creating a branch with your changes, and
2114	@uref{https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/,
2115	submitting a pull request for that branch}.
2116
2117	@item
2118	@cindex AGit workflow, for pull requests
2119	By following the @uref{https://forgejo.org/docs/next/user/agit-support/,
2120	@dfn{AGit workflow}}, which is somewhat more convenient and consumes
2121	less disk space at Codeberg since it removes the need to create a
2122	``fork''.
2123
2124	Assuming your local checkout is on the branch containing the changes you
2125	would like to submit for inclusion in the @code{master} branch, run:
2126
2127	@example
2128	git push origin HEAD:refs/for/master \
2129	-o topic=@var{topic} \
2130	-o title=@var{title} -o description=@var{description}
2131	@end example
2132
2133	@var{topic} must be an identifier without whitespace, similar to a
2134	branch name; @var{title} and @var{description} are arbitrary text that
2135	can be omitted, in which case the message of the last commit on the
2136	branch fills that role.
2137
2138	To send an update to an AGit pull request of yours, run:
2139
2140	@example
2141	git push origin HEAD:refs/for/master \
2142	-o topic=@var{topic} -o force-push=yes
2143	@end example
2144
2145	Codeberg automatically figures out which pull request @var{topic}
2146	corresponds to and updates the associated branch.
2147	@end itemize
2148
2149	Contributors are encouraged to take a moment to set some Git
2150	repository options (@pxref{Configuring Git}) first, which can improve
2151	the readability of patches. Seasoned Guix developers may also want to
2152	look at the section on commit access (@pxref{Commit Access}).
2153
2154	Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
2155	standards, GNU Coding Standards}); you can check the commit history for
2156	examples.
2157
2158	You can help make the review process more efficient, and increase the
2159	chance that your patch will be reviewed quickly, by describing the
2160	context of your patch and the impact you expect it to have. For
2161	example, if your patch is fixing something that is broken, describe the
2162	problem and how your patch fixes it. Tell us how you have tested your
2163	patch. Will users of the code changed by your patch have to adjust
2164	their workflow at all? If so, tell us how. In general, try to imagine
2165	what questions a reviewer will ask, and answer those questions in
2166	advance.
2167
2168	Before submitting a patch that adds or modifies a package definition,
2169	please run through this check list:
2170
2171	@enumerate
2172	@item
2173	If the authors of the packaged software provide a cryptographic
2174	signature for the release tarball, make an effort to verify the
2175	authenticity of the archive. For a detached GPG signature file this
2176	would be done with the @code{gpg --verify} command.
2177
2178	@item
2179	Take some time to provide an adequate synopsis and description for the
2180	package. @xref{Synopses and Descriptions}, for some guidelines.
2181
2182	@item
2183	Run @command{guix lint @var{package}}, where @var{package} is the
2184	name of the new or modified package, and fix any errors it reports
2185	(@pxref{Invoking guix lint}).
2186
2187	@item
2188	Run @command{guix style @var{package}} to format the new package definition
2189	according to the project's conventions (@pxref{Invoking guix style}).
2190
2191	@item
2192	Make sure the package builds on your platform, using @command{guix build
2193	@var{package}}. Also build at least its direct dependents with
2194	@command{guix build --dependents=1 @var{package}}
2195	(@pxref{build-dependents, @command{guix build}}).
2196
2197	@item
2198	We recommend you also try building the package on other supported
2199	platforms. As you may not have access to actual hardware platforms, we
2200	recommend using the @code{qemu-binfmt-service-type} to emulate them. In
2201	order to enable it, add the @code{virtualization} service module and the
2202	following service to the list of services in your @code{operating-system}
2203	configuration:
2204
2205	@lisp
2206	(service qemu-binfmt-service-type
2207	(qemu-binfmt-configuration
2208	(platforms (lookup-qemu-platforms "arm" "aarch64"))))
2209	@end lisp
2210
2211	Then reconfigure your system.
2212
2213	You can then build packages for different platforms by specifying the
2214	@code{--system} option. For example, to build the "hello" package for
2215	the armhf or aarch64 architectures, you would run the following
2216	commands, respectively:
2217	@example
2218	guix build --system=armhf-linux --rounds=2 hello
2219	guix build --system=aarch64-linux --rounds=2 hello
2220	@end example
2221
2222	@item
2223	@cindex bundling
2224	Make sure the package does not use bundled copies of software already
2225	available as separate packages.
2226
2227	Sometimes, packages include copies of the source code of their
2228	dependencies as a convenience for users. However, as a distribution, we
2229	want to make sure that such packages end up using the copy we already
2230	have in the distribution, if there is one. This improves resource usage
2231	(the dependency is built and stored only once), and allows the
2232	distribution to make transverse changes such as applying security
2233	updates for a given software package in a single place and have them
2234	affect the whole system---something that bundled copies prevent.
2235
2236	@item
2237	Take a look at the profile reported by @command{guix size}
2238	(@pxref{Invoking guix size}). This will allow you to notice references
2239	to other packages unwillingly retained. It may also help determine
2240	whether to split the package (@pxref{Packages with Multiple Outputs}),
2241	and which optional dependencies should be used. In particular, avoid
2242	adding @code{texlive} as a dependency: because of its extreme size, use
2243	@code{texlive-local-tree} procedure instead.
2244
2245	@item
2246	Check that dependent packages (if applicable) are not affected by the
2247	change; @command{guix refresh --list-dependent @var{package}} will help you
2248	do that (@pxref{Invoking guix refresh}).
2249
2250	@item
2251	@cindex determinism, of build processes
2252	@cindex reproducible builds, checking
2253	Check whether the package's build process is deterministic. This
2254	typically means checking whether an independent build of the package
2255	yields the exact same result that you obtained, bit for bit.
2256
2257	A simple way to do that is by building the same package several times in
2258	a row on your machine (@pxref{Invoking guix build}):
2259
2260	@example
2261	guix build --rounds=2 my-package
2262	@end example
2263
2264	This is enough to catch a class of common non-determinism issues, such
2265	as timestamps or randomly-generated output in the build result.
2266
2267	Another option is to use @command{guix challenge} (@pxref{Invoking guix
2268	challenge}). You may run it once the package has been committed and
2269	built by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same
2270	result as you did. Better yet: Find another machine that can build it
2271	and run @command{guix publish}. Since the remote build machine is
2272	likely different from yours, this can catch non-determinism issues
2273	related to the hardware---e.g., use of different instruction set
2274	extensions---or to the operating system kernel---e.g., reliance on
2275	@code{uname} or @file{/proc} files.
2276
2277	@item
2278	When writing documentation, please use gender-neutral wording when
2279	referring to people, such as
2280	@uref{https://en.wikipedia.org/wiki/Singular_they, singular
2281	``they''@comma{} ``their''@comma{} ``them''}, and so forth.
2282
2283	@item
2284	Verify that your patch contains only one set of related changes.
2285	Bundling unrelated changes together makes reviewing harder and slower.
2286
2287	Examples of unrelated changes include the addition of several packages,
2288	or a package update along with fixes to that package.
2289
2290	@item
2291	Please follow our code formatting rules, possibly running
2292	@command{guix style} script to do that automatically for you
2293	(@pxref{Formatting Code}).
2294
2295	@item
2296	When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
2297	Use reliable URLs, not generated ones. For instance, GitHub archives are not
2298	necessarily identical from one generation to the next, so in this case it's
2299	often better to clone the repository. Don't use the @code{name} field in
2300	the URL: it is not very useful and if the name changes, the URL will probably
2301	be wrong.
2302
2303	@item
2304	Check if Guix builds (@pxref{Building from Git}) and address the
2305	warnings, especially those about use of undefined symbols.
2306
2307	@item
2308	Make sure your changes do not break Guix and simulate a @command{guix pull}
2309	with:
2310	@example
2311	guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master --disable-authentication
2312	@end example
2313
2314	@end enumerate
2315
2316	@menu
2317	* Configuring Git::
2318	@end menu
2319
2320	@node Configuring Git
2321	@subsection Configuring Git
2322	@cindex git configuration
2323
2324	If you have not done so already, you may wish to set a name and email
2325	that will be associated with your commits (@pxref{telling git your name,
2326	, Telling Git your name, git, Git User Manual}). If you wish to use a
2327	different name or email just for commits in this repository, you can
2328	use @command{git config --local}, or edit @file{.git/config} in the
2329	repository instead of @file{~/.gitconfig}.
2330
2331	Other important Git configuration will automatically be configured when
2332	building the project (@pxref{Building from Git}).
2333
2334	@node Tracking Bugs and Changes
2335	@section Tracking Bugs and Changes
2336
2337	This section describes how the Guix project tracks its bug reports,
2338	patch submissions and topic branches.
2339
2340	@menu
2341	* The Issue Tracker:: The official bug and patch tracker.
2342	* Managing Patches and Branches:: How changes to Guix are managed.
2343	* Cuirass Build Notifications:: Be alerted of any breakage via RSS feeds.
2344	@end menu
2345
2346	@node The Issue Tracker
2347	@subsection The Issue Tracker
2348
2349	Bug reports (@dfn{issues}) and patch submissions (@dfn{pull requests})
2350	are currently tracked at the @uref{https://codeberg.org/guix/guix,
2351	project's home at Codeberg}.
2352
2353	@node Managing Patches and Branches
2354	@subsection Managing Patches and Branches
2355	@cindex branching strategy
2356	@cindex rebuild scheduling strategy
2357
2358	@c TODO: Update when qa.guix is hooked up to Codeberg.
2359	Submitted patches are picked up and tested by the quality assurance
2360	service; the result of that testing eventually shows up on the dashboard
2361	at @indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where
2362	@var{ISSUE_NUMBER} is the number assigned by the issue tracker,
2363	currently Debbugs (work is in progress to support Codeberg pull
2364	requests). Leave time for a review, without committing anything.
2365
2366	As an exception, some changes considered ``trivial'' or ``obvious'' may
2367	be pushed directly to the @code{master} branch. This includes changes
2368	to fix typos and reverting commits that caused immediate problems. This
2369	is subject to being adjusted, allowing individuals to commit directly on
2370	non-controversial changes on parts they’re familiar with.
2371
2372	Changes which affect more than 300 dependent packages (@pxref{Invoking
2373	guix refresh}) should first be pushed to a topic branch other than
2374	@code{master}; the set of changes should be consistent---e.g., ``GNOME
2375	update'', ``NumPy update'', etc. This allows for testing: the branch
2376	will automatically show up at
2377	@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}}, with an
2378	indication of its build status on various platforms.
2379
2380	@cindex feature branches, coordination
2381	To help coordinate the merging of branches, you must create a new
2382	guix-patches issue each time you create a branch (@pxref{The Issue
2383	Tracker}). The title of the issue requesting to merge a branch should
2384	have the following format:
2385
2386	@cindex merge requests, template
2387	@example
2388	Request for merging "@var{name}" branch
2389	@end example
2390
2391	The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such
2392	issues and lists the merge requests on its main page. The following
2393	points apply to managing these branches:
2394
2395	@enumerate
2396	@item
2397	The commits on the branch should be a combination of the patches
2398	relevant to the branch. Patches not related to the topic of the branch
2399	should go elsewhere.
2400
2401	@item
2402	Any changes that can be made on the master branch, should be made on the
2403	master branch. If a commit can be split to apply part of the changes on
2404	master, this is good to do.
2405
2406	@item
2407	It should be possible to re-create the branch by starting from master
2408	and applying the relevant patches.
2409
2410	@item
2411	Avoid merging master in to the branch. Prefer rebasing or re-creating
2412	the branch on top of an updated master revision.
2413
2414	@item
2415	Minimise the changes on master that are missing on the branch prior to
2416	merging the branch in to master. This means that the state of the
2417	branch better reflects the state of master should the branch be merged.
2418
2419	@item
2420	If you don't have commit access, create the ``Request for merging''
2421	issue and request that someone creates the branch. Include a list of
2422	issues/patches to include on the branch.
2423	@end enumerate
2424
2425	Normally branches will be merged in a ``first come, first merged''
2426	manner, tracked through the guix-patches issues. If you agree on a
2427	different order with those involved, you can track this by updating
2428	which issues block@footnote{You can mark an issue as blocked by another
2429	by emailing @email{control@@debbugs.gnu.org} with the following line in
2430	the body of the email: @code{block XXXXX by YYYYY}. Where @code{XXXXX}
2431	is the number for the blocked issue, and @code{YYYYY} is the number for
2432	the issue blocking it.} which other issues. Therefore, to know which
2433	branch is at the front of the queue, look for the oldest issue, or the
2434	issue that isn't @dfn{blocked} by any other branch merges. An ordered
2435	list of branches with the open issues is available at
2436	@url{https://qa.guix.gnu.org}.
2437
2438	Once a branch is at the front of the queue, wait until sufficient time
2439	has passed for the build farms to have processed the changes, and for
2440	the necessary testing to have happened. For example, you can check
2441	@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
2442	information on some builds and substitute availability.
2443
2444	Once the branch has been merged, the issue should be closed and the
2445	branch deleted.
2446
2447	@cindex work-in-progress branches, wip
2448	@cindex wip branches
2449	Sometimes, a branch may be a work in progress, for example for larger
2450	efforts such as updating the GNOME desktop. In these cases, the branch
2451	name should reflect this by having the @samp{wip-} prefix. The QA
2452	infrastructure will avoid building work-in-progress branches, so that
2453	the available resources can be better focused on building the branches
2454	that are ready to be merged. When the branch is no longer a work in
2455	progress, it should be renamed, with the @samp{wip-} prefix removed, and
2456	only then should the merge requests be created, as documented earlier.
2457
2458	@node Cuirass Build Notifications
2459	@subsection Cuirass Build Notifications
2460
2461	@cindex build event notifications, RSS feed
2462	@cindex notifications, build events
2463	Cuirass includes @acronym{RSS, Really Simple Syndication} feeds as one
2464	of its features (@pxref{Notifications,,,cuirass}). Since
2465	@url{https://ci.guix.gnu.org/, Berlin} runs an instance of Cuirass, this
2466	feature can be used to keep track of recently broken or fixed packages
2467	caused by changes pushed to the Guix git repository. Any RSS client can
2468	be used. A good one, included with Emacs, is @xref{Gnus,,,gnus}. To
2469	register the feed, copy its URL, then from the main Gnus buffer,
2470	@samp{Group}, do the following:
2471
2472	@cindex Gnus, configuration to read CI RSS feeds
2473	@cindex RSS feeds, Gnus configuration
2474	@example
2475	@kbd{G R} https://ci.guix.gnu.org/events/rss/?specification=master RET
2476	Guix CI - master RET Build events for specification master. RET
2477	@end example
2478
2479	@noindent
2480	Then, back at the @samp{Group} buffer, press @kbd{s} to save the newly
2481	added RSS group. As for any other Gnus group, you can update its
2482	content by pressing the @kbd{g} key. You should now receive
2483	notifications that read like:
2484
2485	@example
2486	. [ ?: Cuirass ] Build tree-sitter-meson.aarch64-linux on master is fixed.
2487	. [ ?: Cuirass ] Build rust-pbkdf2.aarch64-linux on master is fixed.
2488	. [ ?: Cuirass ] Build rust-pbkdf2.x86_64-linux on master is fixed.
2489	@end example
2490
2491	@noindent
2492	where each RSS entry contains a link to the Cuirass build details page
2493	of the associated build.
2494
2495	@node Teams
2496	@section Teams
2497	@cindex teams
2498
2499	To organize work on Guix, including but not just development efforts,
2500	the project has a set of @dfn{teams}. Each team has its own focus and
2501	interests and is the primary contact point for questions and
2502	contributions in those areas. A team's primary mission is to coordinate
2503	and review the work of individuals in its scope (@pxref{Reviewing the
2504	Work of Others}); it can make decisions within its scope, in agreement
2505	with other teams whenever there is overlap or a close connection, and in
2506	accordance with other project rules such as seeking consensus
2507	(@pxref{Making Decisions}).
2508
2509	As an example, the Python team is responsible for core Python packaging
2510	matters; it can decide to upgrade core Python packages in a dedicated
2511	@code{python-team} branch, in collaboration with any team whose scope is
2512	directly dependent on Python---e.g., the Science team---and following
2513	branching rules (@pxref{Managing Patches and Branches}). The
2514	Documentation team helps review changes to the documentation and can
2515	initiate overarching documentation changes. The Translations team
2516	organizes translation of Guix and its manual and coordinates efforts in
2517	that area. The Core team is responsible for the development of core
2518	functionality and interfaces of Guix; because of its central nature,
2519	some of its work may require soliciting input from the community at
2520	large and seeking consensus before enacting decisions that would affect
2521	the entire community.
2522
2523	Teams are defined in the @file{etc/teams.scm} file in the Guix
2524	repository. The scope of each team is defined, when applicable, as a
2525	set of files or as a regular expression matching file names.
2526
2527	@cindex team membership
2528	Anyone with interest in a team's domain and willing to contribute to its
2529	work can apply to become a member by contacting current members by
2530	email; commit access is not a precondition. Membership is formalized by
2531	adding the person's name and email address to @file{etc/teams.scm}.
2532	Members who have not been participating in the team's work for one year
2533	or more may be removed; they are free to reapply for membership later.
2534
2535	@cindex team creation
2536	One or more people may propose the creation of a new team by reaching
2537	out to the community by email at @email{guix-devel@@gnu.org}, clarifying
2538	the intended scope and purpose. When consensus is reached on the
2539	creation of this team, someone with commit access formalizes its
2540	creation by adding it and its initial members to @file{etc/teams.scm}.
2541
2542	To list existing teams, run the following command from a Guix checkout:
2543
2544	@example
2545	$ ./etc/teams.scm list-teams
2546	id: mentors
2547	name: Mentors
2548	description: A group of mentors who chaperone contributions by newcomers.
2549	members:
2550	+ Charlie Smith <charlie@@example.org>
2551	@dots{}
2552	@end example
2553
2554	@cindex teams, on Codeberg
2555	To generate a @file{CODEOWNERS} file, which Forgejo---the software
2556	behind Codeberg---uses to determine which team or person should review
2557	changes to a given set of files, run:
2558
2559	@example
2560	./etc/teams.scm codeowners > CODEOWNERS
2561	@end example
2562
2563	Teams defined in @file{etc/teams.scm} are reflected
2564	@uref{https://codeberg.org/guix/guix, on Codeberg}; the ``Owners'' team
2565	on Codeberg, whose members have administration privileges over
2566	@uref{https://codeberg.org/guix, the entire ``organization''}, is the
2567	only one missing from this file. To synchronize team changes with
2568	Codeberg, a member of the ``Owners'' team can run:
2569
2570	@example
2571	./etc/teams.scm sync-codeberg-teams @var{token}
2572	@end example
2573
2574	@noindent
2575	... where @var{token} is a token created via the
2576	@url{https://codeberg.org/user/settings/applications, Codeberg
2577	applications settings page}, granting read/write access to the
2578	@samp{organization} permission.
2579
2580	@node Making Decisions
2581	@section Making Decisions
2582
2583	@cindex decision making
2584	@cindex consensus seeking
2585	Every contribution to the project involves a form of decision making.
2586	It is expected from all contributors, and even more so from committers,
2587	to help build consensus and make decisions based on consensus. By using
2588	consensus, we are committed to finding solutions that everyone can live
2589	with. It implies that no decision is made against significant concerns
2590	and these concerns are actively resolved with proposals that work for
2591	everyone.
2592
2593	A contributor (who may or may not have commit access) wishing to block
2594	a proposal bears a special responsibility for finding alternatives,
2595	proposing ideas/code or explain the rationale for the status quo to
2596	resolve the deadlock. To learn what consensus decision making means and
2597	understand its finer details, you are encouraged to read
2598	@url{https://www.seedsforchange.org.uk/consensus}.
2599
2600	Day-to-day decision making, for instance discussions about pull requests
2601	(@pxref{Reviewing the Work of Others}), happens informally among
2602	interested parties such as contributors and members of the relevant
2603	teams (@pxref{Teams}).
2604
2605	@cindex GCD, Guix Consensus Documents
2606	@cindex Guix Consensus Documents (GCD)
2607	Decisions that are expected to have an impact on most contributors
2608	and/or on the broader user community---e.g., changes to project-wide
2609	policies, to core functionality, and so on---are made following the
2610	@acronym{GCD, Guix Consensus Document} process. The process provides a
2611	framework to formalize proposals and draw attention to them, to leave
2612	time for interested parties to discuss them, and to collectively accept
2613	or withdraw them based on input from participating team members. It is
2614	defined in
2615	@uref{https://consensus.guix.gnu.org/gcd/001-gcd-process.html,
2616	GCD@tie{}001}. Past GCDs can be seen at
2617	@uref{https://consensus.guix.gnu.org}, and discussions take place at
2618	@uref{https://codeberg.org/guix/guix-consensus-documents}.
2619
2620	@node Commit Access
2621	@section Commit Access
2622
2623	@cindex commit access, for developers
2624	Everyone can contribute to Guix without having commit access
2625	(@pxref{Submitting Patches}). However, for frequent contributors,
2626	having write access to the repository can be convenient. As a rule of
2627	thumb, a contributor should have accumulated fifty (50) reviewed commits
2628	to be considered as a committer and have sustained their activity in the
2629	project for at least 6 months. This ensures enough interactions with
2630	the contributor, which is essential for mentoring and assessing whether
2631	they are ready to become a committer. Commit access should not be
2632	thought of as a ``badge of honor'' but rather as a responsibility a
2633	contributor is willing to take to help the project.
2634
2635	Committers are in a position where they enact technical decisions. Such
2636	decisions must be made by @emph{actively building consensus} among
2637	interested parties and stakeholders. @xref{Making Decisions}, for more
2638	on that.
2639
2640	The following sections explain how to get commit access, how to be ready
2641	to push commits, and the policies and community expectations for commits
2642	pushed upstream.
2643
2644	@subsection Applying for Commit Access
2645
2646	When you deem it necessary, consider applying for commit
2647	access by following these steps:
2648
2649	@enumerate
2650	@item
2651	Find three committers who would vouch for you. Each of them should
2652	email a statement to @email{guix-maintainers@@gnu.org} (a private alias
2653	for the collective of maintainers), signed with their OpenPGP key.
2654
2655	Committers are expected to have had some interactions with you as a
2656	contributor and to be able to judge whether you are sufficiently
2657	familiar with the project's practices. It is @emph{not} a judgment on
2658	the value of your work, so a refusal should rather be interpreted as
2659	``let's try again later''.
2660
2661	@item
2662	Send @email{guix-maintainers@@gnu.org} a message stating your intent,
2663	listing the three committers who support your application, signed with
2664	the OpenPGP key you will use to sign commits, and giving its fingerprint
2665	(see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
2666	introduction to public-key cryptography with GnuPG.
2667
2668	@c See <https://sha-mbles.github.io/>.
2669	Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
2670	signatures, which is known to be unsafe since 2019, for instance by
2671	adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
2672	Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
2673
2674	@example
2675	digest-algo sha512
2676	@end example
2677
2678	@item
2679	Maintainers ultimately decide whether to grant you commit access,
2680	usually following your referrals' recommendation.
2681
2682	@item
2683	@cindex OpenPGP, signed commits
2684	If and once you've been given access, please send a message to
2685	@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
2686	you will use to sign commits (do that before pushing your first commit).
2687	That way, everyone can notice and ensure you control that OpenPGP key.
2688
2689	@quotation Important
2690	Before you can push for the first time, maintainers must:
2691
2692	@enumerate
2693	@item
2694	add your OpenPGP key to the @code{keyring} branch;
2695	@item
2696	add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
2697	the branch(es) you will commit to.
2698	@end enumerate
2699	@end quotation
2700
2701	@item
2702	Make sure to read the rest of this section and... profit!
2703	@end enumerate
2704
2705	@quotation Note
2706	Maintainers are happy to give commit access to people who have been
2707	contributing for some time and have a track record---don't be shy and
2708	don't underestimate your work!
2709
2710	However, note that the project is working towards a more automated patch
2711	review and merging system, which, as a consequence, may lead us to have
2712	fewer people with commit access to the main repository. Stay tuned!
2713	@end quotation
2714
2715	All commits that are pushed to the central repository on Codeberg must
2716	be signed with an OpenPGP key, and the public key should be uploaded to
2717	your user account on Codeberg and to public key servers, such as
2718	@code{keys.openpgp.org}. To configure Git to automatically sign
2719	commits, run:
2720
2721	@example
2722	git config commit.gpgsign true
2723
2724	# Substitute the fingerprint of your public PGP key.
2725	git config user.signingkey CABBA6EA1DC0FF33
2726	@end example
2727
2728	To check that commits are signed with correct key, use:
2729
2730	@example
2731	guix git authenticate
2732	@end example
2733
2734	@xref{Building from Git} for running the first authentication of a Guix
2735	checkout.
2736
2737	To avoid accidentally pushing unsigned or signed with the wrong key
2738	commits to Codeberg, make sure to configure Git according to
2739	@xref{Configuring Git}.
2740
2741	@subsection Commit Policy
2742
2743	If you get commit access, please make sure to follow the policy below
2744	(discussions of the policy can take place on
2745	@email{guix-devel@@gnu.org}).
2746
2747	Ensure you're aware of how the changes should be handled
2748	(@pxref{Managing Patches and Branches}) prior to being pushed to the
2749	repository, especially for the @code{master} branch.
2750
2751	If you're committing and pushing your own changes, try and wait at least
2752	one week (two weeks for more significant changes, up to one month for
2753	changes such as removing a package---@pxref{package-removal-policy,
2754	Package Removal}) after you send them for review. After this, if no one
2755	else is available to review them and if you're confident about the
2756	changes, it's OK to commit.
2757
2758	When pushing a commit on behalf of somebody else, please add a
2759	@code{Signed-off-by} line at the end of the commit log message---e.g.,
2760	with @command{git am --signoff}. This improves tracking of who did
2761	what.
2762
2763	When adding channel news entries (@pxref{Channels, Writing Channel
2764	News}), make sure they are well-formed by running the following command
2765	right before pushing:
2766
2767	@example
2768	make check-channel-news
2769	@end example
2770
2771	@subsection Addressing Issues
2772
2773	Peer review (@pxref{Submitting Patches}) and tools such as
2774	@command{guix lint} (@pxref{Invoking guix lint}) and the test suite
2775	(@pxref{Running the Test Suite}) should catch issues before they are
2776	pushed. Yet, commits that ``break'' functionality might occasionally
2777	go through. When that happens, there are two priorities: mitigating
2778	the impact, and understanding what happened to reduce the chance of
2779	similar incidents in the future. The responsibility for both these
2780	things primarily lies with those involved, but like everything this is
2781	a group effort.
2782
2783	Some issues can directly affect all users---for instance because they
2784	make @command{guix pull} fail or break core functionality, because they
2785	break major packages (at build time or run time), or because they
2786	introduce known security vulnerabilities.
2787
2788	@cindex reverting commits
2789	The people involved in authoring, reviewing, and pushing such
2790	commit(s) should be at the forefront to mitigate their impact in a
2791	timely fashion: by pushing a followup commit to fix it (if possible),
2792	or by reverting it to leave time to come up with a proper fix, and by
2793	communicating with other developers about the problem.
2794
2795	If these persons are unavailable to address the issue in time, other
2796	committers are entitled to revert the commit(s), explaining in the
2797	commit log and on the mailing list what the problem was, with the goal
2798	of leaving time to the original committer, reviewer(s), and author(s)
2799	to propose a way forward.
2800
2801	Once the problem has been dealt with, it is the responsibility of
2802	those involved to make sure the situation is understood. If you are
2803	working to understand what happened, focus on gathering information
2804	and avoid assigning any blame. Do ask those involved to describe what
2805	happened, do not ask them to explain the situation---this would
2806	implicitly blame them, which is unhelpful. Accountability comes from
2807	a consensus about the problem, learning from it and improving
2808	processes so that it's less likely to reoccur.
2809
2810	@subsubsection Reverting commits
2811
2812	Like normal commits, the commit message should state why the changes are
2813	being made, which in this case would be why the commits are being
2814	reverted.
2815
2816	If the changes are being reverted because they led to excessive number
2817	of packages being affected, then a decision should be made whether to
2818	allow the build farms to build the changes, or whether to avoid
2819	this. For the bordeaux build farm, commits can be ignored by adding them
2820	to the @code{ignore-commits} list in the
2821	@code{build-from-guix-data-service} record, found in the bayfront
2822	machine configuration.
2823
2824	@subsection Commit Revocation
2825
2826	In order to reduce the possibility of mistakes, committers will have
2827	their Codeberg account removed from the Guix Codeberg project and their
2828	key removed from @file{.guix-authorizations} after 12 months of
2829	inactivity; they can ask to regain commit access by emailing the
2830	maintainers, without going through the vouching process.
2831
2832	Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
2833	current list of maintainers. You can email them privately at
2834	@email{guix-maintainers@@gnu.org}.} may also revoke an individual's
2835	commit rights, as a last resort, if cooperation with the rest of the
2836	community has caused too much friction---even within the bounds of the
2837	project's code of conduct (@pxref{Contributing}). They would only do so
2838	after public or private discussion with the individual and a clear
2839	notice. Examples of behavior that hinders cooperation and could lead to
2840	such a decision include:
2841
2842	@itemize
2843	@item repeated violation of the commit policy stated above;
2844	@item repeated failure to take peer criticism into account;
2845	@item breaching trust through a series of grave incidents.
2846	@end itemize
2847
2848	When maintainers resort to such a decision, they notify developers on
2849	@email{guix-devel@@gnu.org}; inquiries may be sent to
2850	@email{guix-maintainers@@gnu.org}. Depending on the situation, the
2851	individual may still be welcome to contribute.
2852
2853	@subsection Helping Out
2854
2855	One last thing: the project keeps moving forward because committers not
2856	only push their own awesome changes, but also offer some of their time
2857	@emph{reviewing} and pushing other people's changes. As a committer,
2858	you're welcome to use your expertise and commit rights to help other
2859	contributors, too!
2860
2861	@node Reviewing the Work of Others
2862	@section Reviewing the Work of Others
2863
2864	Perhaps the biggest action you can do to help GNU Guix grow as a project
2865	is to review the work contributed by others. You do not need to be a
2866	committer to do so; applying, reading the source, building, linting and
2867	running other people's series and sharing your comments about your
2868	experience will give some confidence to committers. You must
2869	ensure the check list found in the @ref{Submitting Patches} section has
2870	been correctly followed. A reviewed patch series should give the best
2871	chances for the proposed change to be merged faster, so if a change you
2872	would like to see merged hasn't yet been reviewed, this is the most
2873	appropriate thing to do! If you would like to review changes in a
2874	specific area and to receive notifications for incoming patches relevant
2875	to that domain, consider joining the relevant team(s) (@pxref{Teams}).
2876
2877	@cindex reviewing, guidelines
2878	Review comments should be unambiguous; be as clear and explicit as you
2879	can about what you think should be changed, ensuring the author can take
2880	action on it. Please try to keep the following guidelines in mind
2881	during review:
2882
2883	@enumerate
2884	@item
2885	@emph{Be clear and explicit about changes you are suggesting}, ensuring
2886	the author can take action on it. In particular, it is a good idea to
2887	explicitly ask for new revisions when you want it.
2888
2889	@item
2890	@emph{Remain focused: do not change the scope of the work being
2891	reviewed.} For example, if the contribution touches code that follows a
2892	pattern deemed unwieldy, it would be unfair to ask the submitter to fix
2893	all occurrences of that pattern in the code; to put it simply, if a
2894	problem unrelated to the patch at hand was already there, do not ask the
2895	submitter to fix it.
2896
2897	@item
2898	@emph{Ensure progress.} As they respond to review, submitters may
2899	submit new revisions of their changes; avoid requesting changes that you
2900	did not request in the previous round of comments. Overall, the
2901	submitter should get a clear sense of progress; the number of items open
2902	for discussion should clearly decrease over time.
2903
2904	@item
2905	@emph{Aim for finalization.} Reviewing code is time-consuming. Your
2906	goal as a reviewer is to put the process on a clear path towards
2907	integration, possibly with agreed-upon changes, or rejection, with a
2908	clear and mutually-understood reasoning. Avoid leaving the review
2909	process in a lingering state with no clear way out.
2910
2911	@item
2912	@emph{Review is a discussion.} The submitter's and reviewer's views on
2913	how to achieve a particular change may not always be aligned. To lead
2914	the discussion, remain focused, ensure progress and aim for
2915	finalization, spending time proportional to the stakes@footnote{The
2916	tendency to discuss minute details at length is often referred to as
2917	``bikeshedding'', where much time is spent discussing each one's
2918	preference for the color of the shed at the expense of progress made on
2919	the project to keep bikes dry.}. As a reviewer, try hard to explain the
2920	rationale for suggestions you make, and to understand and take into
2921	account the submitter's motivation for doing things in a certain way.
2922	In other words, build consensus with everyone involved (@pxref{Making
2923	Decisions}).
2924	@end enumerate
2925
2926	When you deem the proposed change adequate and ready for inclusion
2927	in Guix, you can explicitly say so for pull requests on Codeberg, for
2928	example by selecting ``Approve changes'' in the ``Finish review'' dialog
2929	of the web interface.
2930
2931	@cindex LGTM, Looks Good To Me
2932	@cindex review tags
2933	@cindex Reviewed-by, git trailer
2934	The following well understood/codified
2935	@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
2936	@footnote{The @samp{Reviewed-by} Git trailer is used by other projects
2937	such as Linux, and is understood by third-party tools such as the
2938	@samp{b4 am} sub-command, which is able to retrieve the complete
2939	submission email thread from a public-inbox instance and add the Git
2940	trailers found in replies to the commit patches.} line should be used to
2941	sign off as a reviewer, meaning you have reviewed the change and that it
2942	looks good to you:
2943
2944	@itemize
2945	@item
2946	If the @emph{whole} series (containing multiple commits) looks good to
2947	you, reply with
2948	@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
2949	to the cover page if it has one, or to the last patch of the series
2950	otherwise, adding another @samp{(for the whole series)} comment on the
2951	line below to explicit this fact.
2952
2953	@item
2954	If you instead want to mark a @emph{single commit} as reviewed (but not
2955	the whole series), simply reply with
2956	@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>}
2957	to that commit message.
2958	@end itemize
2959
2960	If you are not a committer, you can help others find a @emph{series} you
2961	have reviewed more easily by adding a @code{reviewed-looks-good} usertag
2962	for the @code{guix} user.
2963
2964	@node Updating the Guix Package
2965	@section Updating the Guix Package
2966
2967	@cindex update-guix-package, updating the guix package
2968	It is sometimes desirable to update the @code{guix} package itself (the
2969	package defined in @code{(gnu packages package-management)}), for
2970	example to make new daemon features available for use by the
2971	@code{guix-service-type} service type. In order to simplify this task,
2972	the following command can be used:
2973
2974	@example
2975	make update-guix-package
2976	@end example
2977
2978	The @code{update-guix-package} make target will use the last known
2979	@emph{commit} corresponding to @code{HEAD} in your Guix checkout,
2980	compute the hash of the Guix sources corresponding to that commit and
2981	update the @code{commit}, @code{revision} and hash of the @code{guix}
2982	package definition.
2983
2984	To validate that the updated @code{guix} package hashes are correct and
2985	that it can be built successfully, the following command can be run from
2986	the directory of your Guix checkout:
2987
2988	@example
2989	./pre-inst-env guix build guix
2990	@end example
2991
2992	To guard against accidentally updating the @code{guix} package to a
2993	commit that others can't refer to, a check is made that the commit used
2994	has already been pushed to the Codeberg-hosted Guix Git repository.
2995
2996	This check can be disabled, @emph{at your own peril}, by setting the
2997	@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
2998	this variable is set, the updated package source is also added to the
2999	store. This is used as part of the release process of Guix.
3000
3001	@node Deprecation Policy
3002	@section Deprecation Policy
3003
3004	@cindex deprecation policy
3005	As any lively project with a broad scope, Guix changes all the time and
3006	at all levels. Because it's user-extensible and programmable,
3007	incompatible changes can directly impact users and make their life
3008	harder. It is thus important to reduce user-visible incompatible
3009	changes to a minimum and, when such changes are deemed necessary, to
3010	clearly communicate them through a @dfn{deprecation period} so everyone
3011	can adapt with minimum hassle. This section defines the project's
3012	commitments for smooth deprecation and describes procedures and
3013	mechanisms to honor them.
3014
3015	There are several ways to use Guix; how to handle deprecation will
3016	depend on each use case. Those can be roughly categorized like this:
3017
3018	@itemize
3019	@item
3020	package management exclusively through the command line;
3021
3022	@item
3023	advanced package management using the manifest and package interfaces;
3024
3025	@item
3026	Home and System management, using the @code{operating-system} and/or
3027	@code{home-environment} interfaces together with the service interfaces;
3028
3029	@item
3030	development or use of external tools that use programming interfaces
3031	such as the @code{(guix ...)} modules.
3032	@end itemize
3033
3034	These use cases form a spectrum with varying degrees of coupling---from
3035	``distant'' to tightly coupled. Based on this insight, we define the
3036	following @dfn{deprecation policies} that we consider suitable for each
3037	of these levels.
3038
3039	@table @asis
3040	@item Command-line tools
3041	Guix sub-commands should be thought of as remaining available
3042	``forever''. Once a Guix sub-command is to be removed, it should be
3043	deprecated first, and then remain available for @b{at least one year}
3044	after the first release that deprecated it.
3045
3046	Deprecation should first be announced in the manual and as an entry in
3047	@file{etc/news.scm}; additional communication such as a blog post
3048	explaining the rationale is welcome. Months before the scheduled
3049	removal date, the command should print a warning explaining how to
3050	migrate. An example of this is the replacement of @command{guix
3051	environment} by @command{guix shell}, started in October
3052	2021@footnote{For more details on the @command{guix shell} transition,
3053	see
3054	@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}.
3055
3056	Because of the broad impact of such a change, we recommend conducting a
3057	user survey before enacting a plan.
3058
3059	@cindex package deprecation
3060	@item Package name changes
3061	When a package name changes, it must remain available under its old name
3062	for @b{at least six months}; the deprecation date should be stated in
3063	a comment in the code to ease the final removal.
3064
3065	For example, @code{go-ipfs} was renamed to
3066	@code{kubo} following a decision made upstream; to communicate the name
3067	change to users, the package module provided this definition:
3068
3069	@findex deprecated-package
3070	@findex define-deprecated-package
3071	@lisp
3072	(define-deprecated-package go-ipfs
3073	kubo)
3074	@end lisp
3075
3076	That way, someone running @command{guix install go-ipfs} or similar sees
3077	a deprecation warning mentioning the new package name; likewise, someone
3078	referring to the @code{go-ipfs} @emph{variable} from their manifest or
3079	package definition will see a warning.
3080
3081	Under the hood, @code{define-deprecated-package} combines
3082	@code{define-deprecated/public-alias} to mark the variable as deprecated
3083	(see below), and the @code{deprecated-package} procedure to mark the
3084	package name as deprecated.
3085
3086	@cindex package removal policy
3087	@anchor{package-removal-policy}
3088	@item Package removal
3089
3090	How packages may be removed depends on their build status and on their
3091	position in the package graph.
3092	@itemize
3093	@item Removal of packages that do not build
3094
3095	A package that does not build becomes a removal candidate immediately.
3096	A pull request removing such a package should be filed on Codeberg
3097	with the @samp{deprecation} label. Additional justification for the
3098	(non-)importance, obsolescence etc. of the package is welcome, but not
3099	required.
3100	Such a pull request may be merged @b{at least three weeks} later if there
3101	is no opposition to the removal or if nobody has volunteered to repair the
3102	affected packages.
3103
3104	@item Removal of building packages
3105
3106	There are various reasons why packages may become removal candidates
3107	although they still build: For instance we may have a newer version of
3108	the same package in Guix, maintenance has stopped upstream, or the package
3109	is not adequately maintained in Guix.
3110
3111	@table @asis
3112	@item Removal candidates that are building leaf packages
3113	Leaf packages may be removed following the above process, assuming that
3114	there is no opposition to the removal or that consensus for the removal
3115	has been reached.
3116	Leaf packages that are typically installed into user profiles (for
3117	instance applications, but also packages used in a service) should
3118	not be removed unless there are particularly good reasons, such as
3119	security implications.
3120
3121	@item Removal candidates that are building packages with dependents
3122	Removing building packages on which other packages depend causes more
3123	disruption than removing leaf packages, since at the same time all
3124	dependent packages need to be removed. This may still be desirable for
3125	overarching reasons. For instance, we want to remove older versions of
3126	packages for which newer versions are already packaged, remove packages
3127	that are unmaintained or have reached end of life upstream, or that suffer
3128	from security vulnerabilities.
3129
3130	In this case, the removal candidate may be removed together with all
3131	packages depending on it following the above procedure. If the removal
3132	candidate falls into the realm of a team, this team must be notified,
3133	and consensus shall be sought about the removal in particular with this
3134	team. Reasonable efforts shall be made beforehand to update or otherwise
3135	preserve dependent packages.
3136
3137	@end table
3138	@end itemize
3139
3140	@quotation Note
3141	Learn about pending package removals by checking
3142	@uref{https://codeberg.org/guix/guix/pulls?labels=445131,
3143	pull requests with the @samp{deprecation} label}.
3144	@end quotation
3145
3146	@item Moving packages between modules
3147
3148	When a package is moved from one module to another one, the corresponding
3149	variable @var{name} should be marked as deprecated in the old location
3150	for @b{at least six months}, for instance by adding
3151	@findex define-deprecated/public-alias
3152	@lisp
3153	(define-deprecated/public-alias @var{name}
3154	(@@ (gnu packages @var{new-module} @var{name}))
3155	@end lisp
3156	in @var{gnu/packages/old-module.scm}.
3157
3158	@item Package additions
3159
3160	Packages submitted for inclusion must not fulfill the criteria to become
3161	a removal candidate immediately after addition.
3162
3163
3164	@cindex service deprecation
3165	@item Services
3166	Changes to services for Guix Home and Guix System have a direct impact
3167	on user configuration. For a user, adjusting to interface changes is
3168	rarely rewarding, which is why any such change must be clearly
3169	communicated in advance through deprecation warnings and documentation.
3170
3171	Renaming of variables related to service, home, or system configuration
3172	must be communicated for at least six months before removal using the
3173	@code{(guix deprecation)} mechanisms. For example, renaming of
3174	@code{murmur-configuration} to @code{mumble-server-configuration} was
3175	communicated through a series of definitions like this one:
3176
3177	@findex define-deprecated/public-alias
3178	@lisp
3179	(define-deprecated/public-alias
3180	murmur-configuration
3181	mumble-server-configuration)
3182	@end lisp
3183
3184	Procedures slated for removal may be defined like this:
3185
3186	@findex define-deprecated
3187	@lisp
3188	(define-deprecated (elogind-service #:key (config (elogind-configuration)))
3189	elogind-service-type
3190	(service elogind-service-type config))
3191	@end lisp
3192
3193	Record fields, notably fields of service configuration records, must
3194	follow a similar deprecation period. This is usually achieved through
3195	@i{ad hoc} means though. For example, the @code{hosts-file} field of
3196	@code{operating-system} was deprecated by adding a @code{sanitized}
3197	property that would emit a warning:
3198
3199	@lisp
3200	(define-record-type* <operating-system>
3201	;; @dots{}
3202	(hosts-file %operating-system-hosts-file ;deprecated
3203	(default #f)
3204	(sanitize warn-hosts-file-field-deprecation)))
3205
3206	(define-deprecated (operating-system-hosts-file os)
3207	hosts-service-type
3208	(%operating-system-hosts-file os))
3209	@end lisp
3210
3211	When deprecating interfaces in @code{operating-system},
3212	@code{home-environment}, @code{(gnu services)}, or any popular service,
3213	the deprecation must come with an entry in @code{etc/news.scm}.
3214
3215	@cindex deprecation of programming interfaces
3216	@item Core interfaces
3217	Core programming interfaces, in particular the @code{(guix ...)}
3218	modules, may be relied on by a variety of external tools and channels.
3219	Any incompatible change must be formally deprecated with
3220	@code{define-deprecated}, as shown above, for @b{at least one year}
3221	before removal. The manual must clearly document the new interface and,
3222	except in obvious cases, explain how to migrate from the old one.
3223
3224	As an example, the @code{build-expression->derivation} procedure was
3225	superseded by @code{gexp->derivation} and remained available as a
3226	deprecated symbol:
3227
3228	@lisp
3229	(define-deprecated (build-expression->derivation store name exp
3230	#:key @dots{})
3231	gexp->derivation
3232	@dots{})
3233	@end lisp
3234
3235	Sometimes bindings are moved from one module to another. In those
3236	cases, bindings must be reexported from the original module for at least
3237	one year.
3238	@end table
3239
3240	This section does not cover all possible situations but hopefully allows
3241	users to know what to expect and developers to stick to its spirit.
3242	Please email @email{guix-devel@@gnu.org} for any questions.
3243
3244	@cindex documentation
3245	@node Writing Documentation
3246	@section Writing Documentation
3247
3248	Guix is documented using the Texinfo system. If you are not yet
3249	familiar with it, we accept contributions for documentation in most
3250	formats. That includes plain text, Markdown, Org, etc.
3251
3252	Documentation contributions can be sent to
3253	@email{guix-patches@@gnu.org}. Prepend @samp{[DOCUMENTATION]} to the
3254	subject.
3255
3256	When you need to make more than a simple addition to the documentation,
3257	we prefer that you send a proper patch as opposed to sending an email
3258	as described above. @xref{Submitting Patches} for more information on
3259	how to send your patches.
3260
3261	To modify the documentation, you need to edit @file{doc/guix.texi} and
3262	@file{doc/contributing.texi} (which contains this documentation
3263	section), or @file{doc/guix-cookbook.texi} for the cookbook. If
3264	you compiled the Guix repository before, you will have
3265	many more @file{.texi} files that are translations of these
3266	documents. Do not modify them, the translation is managed through
3267	@uref{https://translate.codeberg.org/projects/guix, Weblate}.
3268	@xref{Translating Guix} for more information.
3269
3270	To render documentation, you must first make sure that you ran
3271	@command{./configure} in your source tree (@pxref{Running Guix Before
3272	It Is Installed}). After that you can run one of the following
3273	commands:
3274
3275	@itemize
3276	@item @samp{make doc/guix.info} to compile the Info manual.
3277	You can check it with @command{info doc/guix.info}.
3278	@item @samp{make doc/guix.html} to compile the HTML version.
3279	You can point your browser to the relevant file in the
3280	@file{doc/guix.html} directory.
3281	@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
3282	@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
3283	@end itemize
3284
3285	@cindex translation
3286	@cindex l10n
3287	@cindex i18n
3288	@cindex native language support
3289	@node Translating Guix
3290	@section Translating Guix
3291
3292	Writing code and packages is not the only way to provide a meaningful
3293	contribution to Guix. Translating to a language you speak is another
3294	example of a valuable contribution you can make. This section is designed
3295	to describe the translation process. It gives you advice on how you can
3296	get involved, what can be translated, what mistakes you should avoid and
3297	what we can do to help you!
3298
3299	Guix is a big project that has multiple components that can be translated.
3300	We coordinate the translation effort on a
3301	@uref{https://translate.codeberg.org/projects/guix/,Weblate instance}
3302	hosted by Codeberg. You will need an account to submit translations.
3303
3304	Some of the software packaged in Guix also contain translations. We do not
3305	host a translation platform for them. If you want to translate a package
3306	provided by Guix, you should contact their developers or find the information
3307	on their website. As an example, you can find the homepage of the
3308	@code{hello} package by typing @command{guix show hello}. On the ``homepage''
3309	line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.
3310
3311	Many GNU and non-GNU packages can be translated on the
3312	@uref{https://translationproject.org,Translation Project}. Some projects
3313	with multiple components have their own platform. For instance, GNOME has
3314	its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.
3315
3316	Guix has five components hosted on Weblate.
3317
3318	@itemize
3319	@item @code{guix} contains all the strings from the Guix software (the
3320	guided system installer, the package manager, etc), excluding packages.
3321	@item @code{packages} contains the synopsis (single-sentence description
3322	of a package) and description (longer description) of packages in Guix.
3323	@item @code{website} contains the official Guix website, except for
3324	blog posts and multimedia content.
3325	@item @code{documentation-manual} corresponds to this manual.
3326	@item @code{documentation-cookbook} is the component for the cookbook.
3327	@end itemize
3328
3329	@subsubheading General Directions
3330
3331	Once you get an account, you should be able to select a component from
3332	@uref{https://translate.codeberg.org/projects/guix/,the guix project},
3333	and select a language. If your language does not appear in the list, go
3334	to the bottom and click on the ``Start new translation'' button. Select
3335	the language you want to translate to from the list, to start your new
3336	translation.
3337
3338	Like lots of other free software packages, Guix uses
3339	@uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
3340	with which translatable strings are extracted from the source code to so-called
3341	PO files.
3342
3343	Even though PO files are text files, changes should not be made with a text
3344	editor but with PO editing software. Weblate integrates PO editing
3345	functionality. Alternatively, translators can use any of various
3346	free-software tools for filling in translations, of which
3347	@uref{https://poedit.net/,Poedit} is one example, and (after logging in)
3348	@uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
3349	file. There is also a special
3350	@uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
3351	Emacs. Over time translators find out what software they are happy with and
3352	what features they need.
3353
3354	On Weblate, you will find various links to the editor, that will show various
3355	subsets (or all) of the strings. Have a look around and at the
3356	@uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
3357	yourself with the platform.
3358
3359	@subsubheading Translation Components
3360
3361	In this section, we provide more detailed guidance on the translation
3362	process, as well as details on what you should or should not do. When in
3363	doubt, please contact us, we will be happy to help!
3364
3365	@table @asis
3366	@item guix
3367	Guix is written in the Guile programming language, and some strings contain
3368	special formatting that is interpreted by Guile. These special formatting
3369	should be highlighted by Weblate. They start with @code{~} followed by one
3370	or more characters.
3371
3372	When printing the string, Guile replaces the special formatting symbols with
3373	actual values. For instance, the string @samp{ambiguous package specification
3374	`~a'} would be substituted to contain said package specification instead of
3375	@code{~a}. To properly translate this string, you must keep the formatting
3376	code in your translation, although you can place it where it makes sense in
3377	your language. For instance, the French translation says @samp{spécification
3378	du paquet « ~a » ambiguë} because the adjective needs to be placed in the
3379	end of the sentence.
3380
3381	If there are multiple formatting symbols, make sure to respect the order.
3382	Guile does not know in which order you intended the string to be read, so it
3383	will substitute the symbols in the same order as the English sentence.
3384
3385	As an example, you cannot translate @samp{package '~a' has been superseded by
3386	'~a'} by @samp{'~a' supersedes package '~a'}, because the meaning would be
3387	reversed. If @var{foo} is superseded by @var{bar}, the translation would read
3388	@samp{'foo' supersedes package 'bar'}. To work around this problem, it
3389	is possible to use more advanced formatting to select a given piece of data,
3390	instead of following the default English order. @xref{Formatted Output,,,
3391	guile, GNU Guile Reference Manual}, for more information on formatting in Guile.
3392
3393	@item packages
3394
3395	Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
3396	and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}},
3397	@samp{@@emph@{important@}}, etc. When translating, please leave markup as is.
3398
3399	The characters after ``@@'' form the name of the markup, and the text between
3400	``@{'' and ``@}'' is its content. In general, you should not translate the
3401	content of markup like @code{@@code}, as it contains literal code that do not
3402	change with language. You can translate the content of formatting markup such
3403	as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do
3404	not translate the name of the markup, or it will not be recognized. Do
3405	not translate the word after @code{@@end}, it is the name of the markup that
3406	is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).
3407
3408	@item documentation-manual and documentation-cookbook
3409
3410	The first step to ensure a successful translation of the manual is to find
3411	and translate the following strings @emph{first}:
3412
3413	@itemize
3414	@item @code{version.texi}: Translate this string as @code{version-xx.texi},
3415	where @code{xx} is your language code (the one shown in the URL on
3416	weblate).
3417	@item @code{contributing.texi}: Translate this string as
3418	@code{contributing.xx.texi}, where @code{xx} is the same language code.
3419	@item @code{Top}: Do not translate this string, it is important for Texinfo.
3420	If you translate it, the document will be empty (missing a Top node).
3421	Please look for it, and register @code{Top} as its translation.
3422	@end itemize
3423
3424	Translating these strings first ensure we can include your translation in
3425	the guix repository without breaking the make process or the
3426	@command{guix pull} machinery.
3427
3428	The manual and the cookbook both use Texinfo. As for @code{packages}, please
3429	keep Texinfo markup as is. There are more possible markup types in the manual
3430	than in the package descriptions. In general, do not translate the content
3431	of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You
3432	should translate the content of formatting markup such as @code{@@emph},
3433	@code{@@i}, etc.
3434
3435	The manual contains sections that can be referred to by name by @code{@@ref},
3436	@code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do
3437	not have to translate their content. If you keep the English title, we will
3438	automatically replace it with your translation of that title. This ensures
3439	that Texinfo will always be able to find the node. If you decide to change
3440	the translation of the title, the references will automatically be updated
3441	and you will not have to update them all yourself.
3442
3443	When translating references from the cookbook to the manual, you need to
3444	replace the name of the manual and the name of the section. For instance,
3445	to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
3446	Manual@}}, you would replace @code{Defining Packages} with the title of that
3447	section in the translated manual @emph{only} if that title is translated.
3448	If the title is not translated in your language yet, do not translate it here,
3449	or the link will be broken. Replace @code{guix} with @code{guix.xx} where
3450	@code{xx} is your language code. @code{GNU Guix Reference Manual} is the
3451	text of the link. You can translate it however you wish.
3452
3453	@item website
3454
3455	The website pages are written using SXML, an s-expression version of HTML,
3456	the basic language of the web. We have a process to extract translatable
3457	strings from the source, and replace complex s-expressions with a more familiar
3458	XML markup, where each markup is numbered. Translators can arbitrarily change
3459	the ordering, as in the following example.
3460
3461	@example
3462	#. TRANSLATORS: Defining Packages is a section name
3463	#. in the English (en) manual.
3464	#: apps/base/templates/about.scm:64
3465	msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
3466	msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
3467	@end example
3468
3469	Note that you need to include the same markups. You cannot skip any.
3470	@end table
3471
3472	In case you make a mistake, the component might fail to build properly with your
3473	language, or even make guix pull fail. To prevent that, we have a process
3474	in place to check the content of the files before pushing to our repository.
3475	We will not be able to update the translation for your language in Guix, so
3476	we will notify you (through weblate and/or by email) so you get a chance to
3477	fix the issue.
3478
3479	@subsubheading Outside of Weblate
3480
3481	Currently, some parts of Guix cannot be translated on Weblate, help wanted!
3482
3483	@itemize
3484	@item @command{guix pull} news can be translated in @file{news.scm}, but is not
3485	available from Weblate. If you want to provide a translation, you
3486	can prepare a patch as described above, or simply send us your
3487	translation with the name of the news entry you translated and your
3488	language. @xref{Writing Channel News}, for more information about
3489	channel news.
3490	@item Guix blog posts cannot currently be translated.
3491	@item The installer script (for foreign distributions) is entirely in English.
3492	@item Some of the libraries Guix uses cannot be translated or are translated
3493	outside of the Guix project. Guile itself is not internationalized.
3494	@item Other manuals linked from this manual or the cookbook might not be
3495	translated.
3496	@end itemize
3497
3498	@subsubheading Conditions for Inclusion
3499
3500	There are no conditions for adding new translations of the @code{guix} and
3501	@code{guix-packages} components, other than they need at least one translated
3502	string. New languages will be added to Guix as soon as possible. The
3503	files may be removed if they fall out of sync and have no more translated
3504	strings.
3505
3506	Given that the web site is dedicated to new users, we want its translation
3507	to be as complete as possible before we include it in the language menu.
3508	For a new language to be included, it needs to reach at least 80% completion.
3509	When a language is included, it may be removed in the future if it stays
3510	out of sync and falls below 60% completion.
3511
3512	The manual and cookbook are automatically added in the default compilation
3513	target. Every time we synchronize translations, developers need to
3514	recompile all the translated manuals and cookbooks. This is useless for what
3515	is essentially the English manual or cookbook. Therefore, we will only
3516	include a new language when it reaches 10% completion in the component.
3517	When a language is included, it may be removed in the future if it stays
3518	out of sync and falls below 5% completion.
3519
3520	@subsubheading Translation Infrastructure
3521
3522	Weblate is backed by a git repository from which it discovers new strings to
3523	translate and pushes new and updated translations. Normally, it would be
3524	enough to give it commit access to our repositories. However, we decided
3525	to use a separate repository for two reasons. First, we would have to give
3526	Weblate commit access and authorize its signing key, but we do not trust it
3527	in the same way we trust guix developers, especially since we do not manage
3528	the instance ourselves. Second, if translators mess something up, it can
3529	break the generation of the website and/or guix pull for all our users,
3530	independently of their language.
3531
3532	For these reasons, we use a dedicated repository to host translations, and we
3533	synchronize it with our guix and artworks repositories after checking no issue
3534	was introduced in the translation.
3535
3536	Developers can download the latest PO files from weblate in the Guix
3537	repository by running the @command{make download-po} command. It will
3538	automatically download the latest files from weblate, reformat them to a
3539	canonical form, and check they do not contain issues. The manual needs to be
3540	built again to check for additional issues that might crash Texinfo.
3541
3542	Before pushing new translation files, developers should add them to the
3543	make machinery so the translations are actually available. The process
3544	differs for the various components.
3545
3546	@itemize
3547	@item New po files for the @code{guix} and @code{packages} components must
3548	be registered by adding the new language to @file{po/guix/LINGUAS} or
3549	@file{po/packages/LINGUAS}.
3550	@item New po files for the @code{documentation-manual} component must be
3551	registered by adding the file name to @code{DOC_PO_FILES} in
3552	@file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
3553	@code{info_TEXINFOS} in @file{doc/local.mk} and the generated
3554	@file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
3555	@code{TRANSLATED_INFO} also in @file{doc/local.mk}.
3556	@item New po files for the @code{documentation-cookbook} component must be
3557	registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
3558	@file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
3559	manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
3560	@file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
3561	in @file{doc/local.mk}.
3562	@item New po files for the @code{website} component must be added to the
3563	@code{guix-artwork} repository, in @file{website/po/}.
3564	@file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
3565	be updated accordingly (see @file{website/i18n-howto.txt} for more
3566	information on the process).
3567	@end itemize
3568
3569
3570	@cindex infrastructure
3571	@node Contributing to Guix's Infrastructure
3572	@section Contributing to Guix's Infrastructure
3573
3574	Since its inception, the Guix project has always valued its autonomy, and that
3575	reflects in its infrastructure: our servers run Guix System and exclusively
3576	free software, and are administered by volunteers.
3577
3578	Of course this comes at a cost and this is why we need contributions. Our hope
3579	is to make infrastructure-related activity more legible so that maybe you can
3580	picture yourself helping in one of these areas.
3581
3582
3583	@menu
3584	* Coding::
3585	* System Administration::
3586	* Day-to-Day System Administration::
3587	* On-Site Intervention::
3588	* Hosting::
3589	* Administrative Tasks::
3590	@end menu
3591
3592	@node Coding
3593	@subsection Coding
3594
3595	The project runs many Guix-specific services; this is all lovely Scheme code
3596	but it tends to receive less attention than Guix itself:
3597
3598	@itemize
3599	@item
3600	@url{https://git.cbaines.net/guix/bffe, Build Farm Front End}
3601	@item
3602	@url{https://codeberg.org/guix/cuirass/, Cuirass}
3603	@item
3604	@url{https://codeberg.org/guix/maintenance/src/branch/master/hydra/goggles.scm,
3605	Goggles} (IRC logger)
3606	@item
3607	@url{https://codeberg.org/guix/build-coordinator, Guix Build Coordinator}
3608	@item
3609	@url{https://codeberg.org/guix/data-service, Guix Data Service}
3610	@item
3611	@url{https://codeberg.org/luis-felipe/guix-packages-website,
3612	Guix Packages Website}
3613	@item
3614	@url{https://codeberg.org/guix/mumi, mumi}
3615	@item
3616	@url{https://codeberg.org/guix/nar-herder, Nar Herder}
3617	@item
3618	@url{https://codeberg.org/guix/qa-frontpage, QA Frontpage}
3619	@end itemize
3620
3621	There is no time constraint on this coding activity: any improvement is
3622	welcome, whenever it comes. Most of these code bases are relatively small,
3623	which should make it easier to get started.
3624
3625	Prerequisites: Familiarity with Guile, HTTP, and databases.
3626
3627	If you wish to get started, check out the README of the project of your choice
3628	and get in touch with guix-devel and the primary developer(s) of the tool as
3629	per @code{git shortlog -s \| sort -k1 -n}.
3630
3631	@node System Administration
3632	@subsection System Administration
3633
3634	Guix System configuration for all our systems is held in this repository:
3635
3636	@url{https://codeberg.org/guix/maintenance.git/src/branch/master/hydra/}
3637
3638	The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org)
3639	and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org,
3640	guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more). Both connect to a
3641	number of build machines and helpers.
3642
3643	Without even having SSH access to the machine, you can help by posting patches
3644	to improve the configuration (you can test it with @code{guix system vm}).
3645	Here are ways you can help:
3646
3647	@itemize
3648	@item
3649	Improve infra monitoring: set up a dashboard to monitor all the infrastructure,
3650	and an out-of-band channel to communicate about downtime.
3651
3652	@item
3653	Implement web site redundancy: guix.gnu.org should be backed by several
3654	machines on different sites. Get in touch with us and/or send a patch!
3655
3656	@item
3657	Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and
3658	ci.guix.gnu.org should be backed by several head nodes.
3659
3660	@item
3661	Improve backup: there's currently ad-hoc backup of selected pieces over rsync
3662	between the two head nodes; we can improve on that, for example with a
3663	dedicated backup site and proper testing of recoverability.
3664
3665	@item
3666	Support mirroring: We'd like to make it easy for others to mirror substitutes
3667	from ci.guix and bordeaux.guix, perhaps by offering public rsync access.
3668
3669	@item
3670	Optimize our web services: Monitor the performance of our services and tweak
3671	nginx config or whatever it takes to improve it.
3672
3673	There is no time constraint on this activity: any improvement is welcome,
3674	whenever you can work on it.
3675
3676	Prerequisite: Familiarity with Guix System administration and ideally with the
3677	infrastructure handbook:
3678
3679	@url{https://codeberg.org/guix/maintenance.git/src/branch/master/doc/infra-handbook.org,
3680	Infra-Handbook}
3681
3682	@end itemize
3683
3684	@node Day-to-Day System Administration
3685	@subsection Day-to-Day System Administration
3686
3687	We're also looking for people who'd be willing to have SSH access to some of
3688	the infrastructure to help with day-to-day maintenance: restarting a build,
3689	restarting the occasional service that has gone wild (that can happen),
3690	reconfiguring/upgrading a machine, rebooting, etc.
3691
3692	This day-to-day activity requires you to be available some of the time (during
3693	office hours or not, during the week-end or not), whenever is convenient for
3694	you, so you can react to issues reported on IRC, on the mailing list, or
3695	elsewhere, and synchronize with other sysadmins.
3696
3697	Prerequisite: Being a ``known'' member of the community, familiarity with Guix
3698	System administration, with some of the services/web sites being run, and with
3699	the infrastructure handbook:
3700
3701	@url{https://codeberg.org/guix/maintenance.git/src/branch/master/doc/infra-handbook.org,
3702	Infra-Handbook}
3703
3704	@node On-Site Intervention
3705	@subsection On-Site Intervention
3706
3707	The first front-end is currently generously hosted by the Max Delbrück Center
3708	(MDC), a research institute in Berlin, Germany. Only authorized personnel can
3709	physically access it.
3710
3711	The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a
3712	professional data center shared with non-profit ISP Aquilenet. If you live in
3713	the region of Bordeaux and would like to help out when we need to go on-site,
3714	please make yourself known by emailing @email{guix-sysadmin@@gnu.org}.
3715
3716	On-site interventions are rare, but they're usually in response to an
3717	emergency.
3718
3719	@node Hosting
3720	@subsection Hosting
3721
3722	We're looking for people who can host machines and help out whenever
3723	physical access is needed. More specifically:
3724
3725	@itemize
3726	@item
3727	We need hosting of ``small'' machines such as single-board computers (AArch64,
3728	RISC-V) for use as build machines.
3729
3730	@item
3731	We need hosting for front-ends and x86_64 build machines in a data center where
3732	they can be racked and where, ideally, several local Guix sysadmins can
3733	physically access them.
3734	@end itemize
3735
3736	The machines should be accessible over Wireguard VPN most of the
3737	time, so longer power or network interruptions should be the
3738	exception.
3739
3740	Prerequisites: Familiarity with installing and remotely administering Guix
3741	System.
3742
3743	@node Administrative Tasks
3744	@subsection Administrative Tasks
3745
3746	The infra remains up and running thanks to crucial administrative tasks, which
3747	includes:
3748
3749	@itemize
3750	@item
3751	Selecting and purchasing hardware, for example build machines.
3752	@item
3753	Renewing domain names.
3754
3755	@item
3756	Securing funding, in particular via the Guix Foundation:
3757	@url{https://foundation.guix.info, Guix Foundation}
3758	@end itemize
3759
3760	Prerequisites: Familiarity with hardware, and/or DNS registrars,
3761	and/or sponsorship, and/or crowdfunding.