etc: snippets: Add guix-commit-message-use-https-home-page.
[jackhill/guix/guix.git] / doc / contributing.texi
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 Freenode 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{http://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 * Building from Git:: The latest and greatest.
24 * Running Guix Before It Is Installed:: Hacker tricks.
25 * The Perfect Setup:: The right tools.
26 * Coding Style:: Hygiene of the contributor.
27 * Submitting Patches:: Share your work.
28 @end menu
29
30 @node Building from Git
31 @section Building from Git
32
33 If you want to hack Guix itself, it is recommended to use the latest
34 version from the Git repository:
35
36 @example
37 git clone https://git.savannah.gnu.org/git/guix.git
38 @end example
39
40 When building Guix from a checkout,
41 the following packages are required in addition to those mentioned in
42 the installation instructions (@pxref{Requirements}).
43
44 @itemize
45 @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
46 @item @url{http://gnu.org/software/automake/, GNU Automake};
47 @item @url{http://gnu.org/software/gettext/, GNU Gettext};
48 @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
49 @item @url{http://www.graphviz.org/, Graphviz};
50 @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
51 @end itemize
52
53 The easiest way to set up a development environment for Guix is, of
54 course, by using Guix! The following command starts a new shell where
55 all the dependencies and appropriate environment variables are set up to
56 hack on Guix:
57
58 @example
59 guix environment guix
60 @end example
61
62 @xref{Invoking guix environment}, for more information on that command.
63 Extra dependencies can be added with @option{--ad-hoc}:
64
65 @example
66 guix environment guix --ad-hoc help2man git strace
67 @end example
68
69 Run @command{./bootstrap} to generate the build system infrastructure
70 using Autoconf and Automake. If you get an error like this one:
71
72 @example
73 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
74 @end example
75
76 @noindent
77 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
78 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
79 same holds for the @file{guile.m4} set of macros provided by Guile. For
80 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
81 look for @file{.m4} files in @file{/usr/share}. In that case, you have
82 to invoke the following command:
83
84 @example
85 export ACLOCAL_PATH=/usr/share/aclocal
86 @end example
87
88 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
89 more information.
90
91 Then, run @command{./configure} as usual. Make sure to pass
92 @code{--localstatedir=@var{directory}} where @var{directory} is the
93 @code{localstatedir} value used by your current installation (@pxref{The
94 Store}, for information about this).
95
96 Finally, you have to invoke @code{make check} to run tests
97 (@pxref{Running the Test Suite}). If anything
98 fails, take a look at installation instructions (@pxref{Installation})
99 or send a message to the @email{guix-devel@@gnu.org, mailing list}.
100
101
102 @node Running Guix Before It Is Installed
103 @section Running Guix Before It Is Installed
104
105 In order to keep a sane working environment, you will find it useful to
106 test the changes made in your local source tree checkout without
107 actually installing them. So that you can distinguish between your
108 ``end-user'' hat and your ``motley'' costume.
109
110 To that end, all the command-line tools can be used even if you have not
111 run @code{make install}. To do that, you first need to have an environment
112 with all the dependencies available (@pxref{Building from Git}), and then
113 simply prefix each command with
114 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
115 top build tree of Guix), as in@footnote{The @option{-E} flag to
116 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
117 such that @command{guix-daemon} and the tools it uses can find the Guile
118 modules they need.}:
119
120 @example
121 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
122 $ ./pre-inst-env guix build hello
123 @end example
124
125 @noindent
126 Similarly, for a Guile session using the Guix modules:
127
128 @example
129 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
130
131 ;;; ("x86_64-linux")
132 @end example
133
134 @noindent
135 @cindex REPL
136 @cindex read-eval-print loop
137 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
138 Reference Manual}):
139
140 @example
141 $ ./pre-inst-env guile
142 scheme@@(guile-user)> ,use(guix)
143 scheme@@(guile-user)> ,use(gnu)
144 scheme@@(guile-user)> (define snakes
145 (fold-packages
146 (lambda (package lst)
147 (if (string-prefix? "python"
148 (package-name package))
149 (cons package lst)
150 lst))
151 '()))
152 scheme@@(guile-user)> (length snakes)
153 $1 = 361
154 @end example
155
156 The @command{pre-inst-env} script sets up all the environment variables
157 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
158
159 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
160 local source tree; it simply updates the @file{~/.config/guix/current}
161 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
162 you want to upgrade your local source tree.
163
164
165 @node The Perfect Setup
166 @section The Perfect Setup
167
168 The Perfect Setup to hack on Guix is basically the perfect setup used
169 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
170 Manual}). First, you need more than an editor, you need
171 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
172 wonderful @url{http://nongnu.org/geiser/, Geiser}.
173
174 Geiser allows for interactive and incremental development from within
175 Emacs: code compilation and evaluation from within buffers, access to
176 on-line documentation (docstrings), context-sensitive completion,
177 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
178 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
179 convenient Guix development, make sure to augment Guile’s load path so
180 that it finds source files from your checkout:
181
182 @lisp
183 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
184 (with-eval-after-load 'geiser-guile
185 (add-to-list 'geiser-guile-load-path "~/src/guix"))
186 @end lisp
187
188 To actually edit the code, Emacs already has a neat Scheme mode. But in
189 addition to that, you must not miss
190 @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
191 facilities to directly operate on the syntax tree, such as raising an
192 s-expression or wrapping it, swallowing or rejecting the following
193 s-expression, etc.
194
195 @cindex code snippets
196 @cindex templates
197 @cindex reducing boilerplate
198 We also provide templates for common git commit messages and package
199 definitions in the @file{etc/snippets} directory. These templates can
200 be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
201 expand short trigger strings to interactive text snippets. You may want
202 to add the snippets directory to the @var{yas-snippet-dirs} variable in
203 Emacs.
204
205 @lisp
206 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
207 (with-eval-after-load 'yasnippet
208 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
209 @end lisp
210
211 The commit message snippets depend on @url{https://magit.vc/, Magit} to
212 display staged files. When editing a commit message type @code{add}
213 followed by @kbd{TAB} to insert a commit message template for adding a
214 package; type @code{update} followed by @kbd{TAB} to insert a template
215 for updating a package; type @code{https} followed by @kbd{TAB} to
216 insert a template for changing the home page URI of a package to HTTPS.
217
218 The main snippet for @code{scheme-mode} is triggered by typing
219 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
220 trigger string @code{origin...}, which can be expanded further. The
221 @code{origin} snippet in turn may insert other trigger strings ending on
222 @code{...}, which also can be expanded further.
223
224
225 @node Coding Style
226 @section Coding Style
227
228 In general our code follows the GNU Coding Standards (@pxref{Top,,,
229 standards, GNU Coding Standards}). However, they do not say much about
230 Scheme, so here are some additional rules.
231
232 @menu
233 * Programming Paradigm:: How to compose your elements.
234 * Modules:: Where to store your code?
235 * Data Types and Pattern Matching:: Implementing data structures.
236 * Formatting Code:: Writing conventions.
237 @end menu
238
239 @node Programming Paradigm
240 @subsection Programming Paradigm
241
242 Scheme code in Guix is written in a purely functional style. One
243 exception is code that involves input/output, and procedures that
244 implement low-level concepts, such as the @code{memoize} procedure.
245
246 @node Modules
247 @subsection Modules
248
249 Guile modules that are meant to be used on the builder side must live in
250 the @code{(guix build @dots{})} name space. They must not refer to
251 other Guix or GNU modules. However, it is OK for a ``host-side'' module
252 to use a build-side module.
253
254 Modules that deal with the broader GNU system should be in the
255 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
256
257 @node Data Types and Pattern Matching
258 @subsection Data Types and Pattern Matching
259
260 The tendency in classical Lisp is to use lists to represent everything,
261 and then to browse them ``by hand'' using @code{car}, @code{cdr},
262 @code{cadr}, and co. There are several problems with that style,
263 notably the fact that it is hard to read, error-prone, and a hindrance
264 to proper type error reports.
265
266 Guix code should define appropriate data types (for instance, using
267 @code{define-record-type*}) rather than abuse lists. In addition, it
268 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
269 especially when matching lists.
270
271 @node Formatting Code
272 @subsection Formatting Code
273
274 @cindex formatting code
275 @cindex coding style
276 When writing Scheme code, we follow common wisdom among Scheme
277 programmers. In general, we follow the
278 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
279 Style Rules}. This document happens to describe the conventions mostly
280 used in Guile’s code too. It is very thoughtful and well written, so
281 please do read it.
282
283 Some special forms introduced in Guix, such as the @code{substitute*}
284 macro, have special indentation rules. These are defined in the
285 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
286 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
287 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
288 Emacs-Guix Reference Manual}).
289
290 @cindex indentation, of code
291 @cindex formatting, of code
292 If you do not use Emacs, please make sure to let your editor knows these
293 rules. To automatically indent a package definition, you can also run:
294
295 @example
296 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
297 @end example
298
299 @noindent
300 This automatically indents the definition of @var{package} in
301 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
302 indent a whole file, omit the second argument:
303
304 @example
305 ./etc/indent-code.el gnu/services/@var{file}.scm
306 @end example
307
308 @cindex Vim, Scheme code editing
309 If you are editing code with Vim, we recommend that you run @code{:set
310 autoindent} so that your code is automatically indented as you type.
311 Additionally,
312 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
313 @code{paredit.vim}} may help you deal with all these parentheses.
314
315 We require all top-level procedures to carry a docstring. This
316 requirement can be relaxed for simple private procedures in the
317 @code{(guix build @dots{})} name space, though.
318
319 Procedures should not have more than four positional parameters. Use
320 keyword parameters for procedures that take more than four parameters.
321
322
323 @node Submitting Patches
324 @section Submitting Patches
325
326 Development is done using the Git distributed version control system.
327 Thus, access to the repository is not strictly necessary. We welcome
328 contributions in the form of patches as produced by @code{git
329 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
330
331 This mailing list is backed by a Debbugs instance accessible at
332 @uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track
333 of submissions. Each message sent to that mailing list gets a new
334 tracking number assigned; people can then follow up on the submission by
335 sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
336 the tracking number (@pxref{Sending a Patch Series}).
337
338 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
339 standards, GNU Coding Standards}); you can check the commit history for
340 examples.
341
342 Before submitting a patch that adds or modifies a package definition,
343 please run through this check list:
344
345 @enumerate
346 @item
347 If the authors of the packaged software provide a cryptographic
348 signature for the release tarball, make an effort to verify the
349 authenticity of the archive. For a detached GPG signature file this
350 would be done with the @code{gpg --verify} command.
351
352 @item
353 Take some time to provide an adequate synopsis and description for the
354 package. @xref{Synopses and Descriptions}, for some guidelines.
355
356 @item
357 Run @code{guix lint @var{package}}, where @var{package} is the
358 name of the new or modified package, and fix any errors it reports
359 (@pxref{Invoking guix lint}).
360
361 @item
362 Make sure the package builds on your platform, using @code{guix build
363 @var{package}}.
364
365 @item
366 @cindex bundling
367 Make sure the package does not use bundled copies of software already
368 available as separate packages.
369
370 Sometimes, packages include copies of the source code of their
371 dependencies as a convenience for users. However, as a distribution, we
372 want to make sure that such packages end up using the copy we already
373 have in the distribution, if there is one. This improves resource usage
374 (the dependency is built and stored only once), and allows the
375 distribution to make transverse changes such as applying security
376 updates for a given software package in a single place and have them
377 affect the whole system---something that bundled copies prevent.
378
379 @item
380 Take a look at the profile reported by @command{guix size}
381 (@pxref{Invoking guix size}). This will allow you to notice references
382 to other packages unwillingly retained. It may also help determine
383 whether to split the package (@pxref{Packages with Multiple Outputs}),
384 and which optional dependencies should be used.
385
386 @item
387 For important changes, check that dependent package (if applicable) are
388 not affected by the change; @code{guix refresh --list-dependent
389 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
390
391 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
392 @cindex branching strategy
393 @cindex rebuild scheduling strategy
394 Depending on the number of dependent packages and thus the amount of
395 rebuilding induced, commits go to different branches, along these lines:
396
397 @table @asis
398 @item 300 dependent packages or less
399 @code{master} branch (non-disruptive changes).
400
401 @item between 300 and 1,200 dependent packages
402 @code{staging} branch (non-disruptive changes). This branch is intended
403 to be merged in @code{master} every 3 weeks or so. Topical changes
404 (e.g., an update of the GNOME stack) can instead go to a specific branch
405 (say, @code{gnome-updates}).
406
407 @item more than 1,200 dependent packages
408 @code{core-updates} branch (may include major and potentially disruptive
409 changes). This branch is intended to be merged in @code{master} every
410 2.5 months or so.
411 @end table
412
413 All these branches are @uref{https://hydra.gnu.org/project/gnu,
414 tracked by our build farm} and merged into @code{master} once
415 everything has been successfully built. This allows us to fix issues
416 before they hit users, and to reduce the window during which pre-built
417 binaries are not available.
418
419 Generally, branches other than @code{master} are considered
420 @emph{frozen} if there has been a recent evaluation, or there is a
421 corresponding @code{-next} branch. Please ask on the mailing list or
422 IRC if unsure where to place a patch.
423 @c TODO: It would be good with badges on the website that tracks these
424 @c branches. Or maybe even a status page.
425
426 @item
427 @cindex determinism, of build processes
428 @cindex reproducible builds, checking
429 Check whether the package's build process is deterministic. This
430 typically means checking whether an independent build of the package
431 yields the exact same result that you obtained, bit for bit.
432
433 A simple way to do that is by building the same package several times in
434 a row on your machine (@pxref{Invoking guix build}):
435
436 @example
437 guix build --rounds=2 my-package
438 @end example
439
440 This is enough to catch a class of common non-determinism issues, such
441 as timestamps or randomly-generated output in the build result.
442
443 Another option is to use @command{guix challenge} (@pxref{Invoking guix
444 challenge}). You may run it once the package has been committed and
445 built by @code{hydra.gnu.org} to check whether it obtains the same
446 result as you did. Better yet: Find another machine that can build it
447 and run @command{guix publish}. Since the remote build machine is
448 likely different from yours, this can catch non-determinism issues
449 related to the hardware---e.g., use of different instruction set
450 extensions---or to the operating system kernel---e.g., reliance on
451 @code{uname} or @file{/proc} files.
452
453 @item
454 When writing documentation, please use gender-neutral wording when
455 referring to people, such as
456 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
457 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
458
459 @item
460 Verify that your patch contains only one set of related changes.
461 Bundling unrelated changes together makes reviewing harder and slower.
462
463 Examples of unrelated changes include the addition of several packages,
464 or a package update along with fixes to that package.
465
466 @item
467 Please follow our code formatting rules, possibly running the
468 @command{etc/indent-code.el} script to do that automatically for you
469 (@pxref{Formatting Code}).
470
471 @end enumerate
472
473 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
474 a subject. You may use your email client or the @command{git
475 send-email} command (@pxref{Sending a Patch Series}). We prefer to get
476 patches in plain text messages, either inline or as MIME attachments.
477 You are advised to pay attention if your email client changes anything
478 like line breaks or indentation which could potentially break the
479 patches.
480
481 When a bug is resolved, please close the thread by sending an email to
482 @email{@var{NNN}-done@@debbugs.gnu.org}.
483
484 @unnumberedsubsec Sending a Patch Series
485 @anchor{Sending a Patch Series}
486 @cindex patch series
487 @cindex @code{git send-email}
488 @cindex @code{git-send-email}
489
490 When sending a patch series (e.g., using @code{git send-email}), please
491 first send one message to @email{guix-patches@@gnu.org}, and then send
492 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
493 they are kept together. See
494 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
495 for more information.
496 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html