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.  When building Guix from a checkout,
  35 the following packages are required in addition to those mentioned in
  36 the installation instructions (@pxref{Requirements}).
  37
  38 @itemize
  39 @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
  40 @item @url{http://gnu.org/software/automake/, GNU Automake};
  41 @item @url{http://gnu.org/software/gettext/, GNU Gettext};
  42 @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
  43 @item @url{http://www.graphviz.org/, Graphviz};
  44 @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
  45 @end itemize
  46
  47 The easiest way to set up a development environment for Guix is, of
  48 course, by using Guix!  The following command starts a new shell where
  49 all the dependencies and appropriate environment variables are set up to
  50 hack on Guix:
  51
  52 @example
  53 guix environment guix
  54 @end example
  55
  56 @xref{Invoking guix environment}, for more information on that command.
  57 Extra dependencies can be added with @option{--ad-hoc}:
  58
  59 @example
  60 guix environment guix --ad-hoc help2man git strace
  61 @end example
  62
  63 Run @command{./bootstrap} to generate the build system infrastructure
  64 using Autoconf and Automake.  If you get an error like this one:
  65
  66 @example
  67 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
  68 @end example
  69
  70 @noindent
  71 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
  72 provided by pkg-config.  Make sure that @file{pkg.m4} is available.  The
  73 same holds for the @file{guile.m4} set of macros provided by Guile.  For
  74 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
  75 look for @file{.m4} files in @file{/usr/share}.  In that case, you have
  76 to invoke the following command:
  77
  78 @example
  79 export ACLOCAL_PATH=/usr/share/aclocal
  80 @end example
  81
  82 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
  83 more information.
  84
  85 Then, run @command{./configure} as usual.  Make sure to pass
  86 @code{--localstatedir=@var{directory}} where @var{directory} is the
  87 @code{localstatedir} value used by your current installation (@pxref{The
  88 Store}, for information about this).
  89
  90 Finally, you have to invoke @code{make check} to run tests
  91 (@pxref{Running the Test Suite}).  If anything
  92 fails, take a look at installation instructions (@pxref{Installation})
  93 or send a message to the @email{guix-devel@@gnu.org, mailing list}.
  94
  95
  96 @node Running Guix Before It Is Installed
  97 @section Running Guix Before It Is Installed
  98
  99 In order to keep a sane working environment, you will find it useful to
 100 test the changes made in your local source tree checkout without
 101 actually installing them.  So that you can distinguish between your
 102 ``end-user'' hat and your ``motley'' costume.
 103
 104 To that end, all the command-line tools can be used even if you have not
 105 run @code{make install}.  To do that, prefix each command with
 106 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
 107 top build tree of Guix), as in:
 108
 109 @example
 110 $ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
 111 $ ./pre-inst-env guix build hello
 112 @end example
 113
 114 @noindent
 115 Similarly, for a Guile session using the Guix modules:
 116
 117 @example
 118 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
 119
 120 ;;; ("x86_64-linux")
 121 @end example
 122
 123 @noindent
 124 @cindex REPL
 125 @cindex read-eval-print loop
 126 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
 127 Reference Manual}):
 128
 129 @example
 130 $ ./pre-inst-env guile
 131 scheme@@(guile-user)> ,use(guix)
 132 scheme@@(guile-user)> ,use(gnu)
 133 scheme@@(guile-user)> (define snakes
 134                        (fold-packages
 135                          (lambda (package lst)
 136                            (if (string-prefix? "python"
 137                                                (package-name package))
 138                                (cons package lst)
 139                                lst))
 140                          '()))
 141 scheme@@(guile-user)> (length snakes)
 142 $1 = 361
 143 @end example
 144
 145 The @command{pre-inst-env} script sets up all the environment variables
 146 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
 147
 148 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
 149 local source tree; it simply updates the @file{~/.config/guix/latest}
 150 symlink (@pxref{Invoking guix pull}).  Run @command{git pull} instead if
 151 you want to upgrade your local source tree.@footnote{If you would like
 152 to set up @command{guix} to use your Git checkout, you can point the
 153 @file{~/.config/guix/latest} symlink to your Git checkout directory.
 154 If you are the sole user of your system, you may also consider pointing
 155 the @file{/root/.config/guix/latest} symlink to point to
 156 @file{~/.config/guix/latest}; this way it will always use the same
 157 @command{guix} as your user does.}
 158
 159
 160 @node The Perfect Setup
 161 @section The Perfect Setup
 162
 163 The Perfect Setup to hack on Guix is basically the perfect setup used
 164 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
 165 Manual}).  First, you need more than an editor, you need
 166 @url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
 167 wonderful @url{http://nongnu.org/geiser/, Geiser}.
 168
 169 Geiser allows for interactive and incremental development from within
 170 Emacs: code compilation and evaluation from within buffers, access to
 171 on-line documentation (docstrings), context-sensitive completion,
 172 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
 173 and more (@pxref{Introduction,,, geiser, Geiser User Manual}).  For
 174 convenient Guix development, make sure to augment Guile’s load path so
 175 that it finds source files from your checkout:
 176
 177 @lisp
 178 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
 179 (with-eval-after-load 'geiser-guile
 180   (add-to-list 'geiser-guile-load-path "~/src/guix"))
 181 @end lisp
 182
 183 To actually edit the code, Emacs already has a neat Scheme mode.  But in
 184 addition to that, you must not miss
 185 @url{http://www.emacswiki.org/emacs/ParEdit, Paredit}.  It provides
 186 facilities to directly operate on the syntax tree, such as raising an
 187 s-expression or wrapping it, swallowing or rejecting the following
 188 s-expression, etc.
 189
 190
 191 @node Coding Style
 192 @section Coding Style
 193
 194 In general our code follows the GNU Coding Standards (@pxref{Top,,,
 195 standards, GNU Coding Standards}).  However, they do not say much about
 196 Scheme, so here are some additional rules.
 197
 198 @menu
 199 * Programming Paradigm::        How to compose your elements.
 200 * Modules::                     Where to store your code?
 201 * Data Types and Pattern Matching::  Implementing data structures.
 202 * Formatting Code::             Writing conventions.
 203 @end menu
 204
 205 @node Programming Paradigm
 206 @subsection Programming Paradigm
 207
 208 Scheme code in Guix is written in a purely functional style.  One
 209 exception is code that involves input/output, and procedures that
 210 implement low-level concepts, such as the @code{memoize} procedure.
 211
 212 @node Modules
 213 @subsection Modules
 214
 215 Guile modules that are meant to be used on the builder side must live in
 216 the @code{(guix build @dots{})} name space.  They must not refer to
 217 other Guix or GNU modules.  However, it is OK for a ``host-side'' module
 218 to use a build-side module.
 219
 220 Modules that deal with the broader GNU system should be in the
 221 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
 222
 223 @node Data Types and Pattern Matching
 224 @subsection Data Types and Pattern Matching
 225
 226 The tendency in classical Lisp is to use lists to represent everything,
 227 and then to browse them ``by hand'' using @code{car}, @code{cdr},
 228 @code{cadr}, and co.  There are several problems with that style,
 229 notably the fact that it is hard to read, error-prone, and a hindrance
 230 to proper type error reports.
 231
 232 Guix code should define appropriate data types (for instance, using
 233 @code{define-record-type*}) rather than abuse lists.  In addition, it
 234 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
 235 especially when matching lists.
 236
 237 @node Formatting Code
 238 @subsection Formatting Code
 239
 240 When writing Scheme code, we follow common wisdom among Scheme
 241 programmers.  In general, we follow the
 242 @url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
 243 Style Rules}.  This document happens to describe the conventions mostly
 244 used in Guile’s code too.  It is very thoughtful and well written, so
 245 please do read it.
 246
 247 Some special forms introduced in Guix, such as the @code{substitute*}
 248 macro, have special indentation rules.  These are defined in the
 249 @file{.dir-locals.el} file, which Emacs automatically uses.  If you do
 250 not use Emacs, please make sure to let your editor know the rules.
 251
 252 We require all top-level procedures to carry a docstring.  This
 253 requirement can be relaxed for simple private procedures in the
 254 @code{(guix build @dots{})} name space, though.
 255
 256 Procedures should not have more than four positional parameters.  Use
 257 keyword parameters for procedures that take more than four parameters.
 258
 259
 260 @node Submitting Patches
 261 @section Submitting Patches
 262
 263 Development is done using the Git distributed version control system.
 264 Thus, access to the repository is not strictly necessary.  We welcome
 265 contributions in the form of patches as produced by @code{git
 266 format-patch} sent to the @email{guix-devel@@gnu.org, mailing list}.
 267 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 268 standards, GNU Coding Standards}); you can check the commit history for
 269 examples.
 270
 271 Before submitting a patch that adds or modifies a package definition,
 272 please run through this check list:
 273
 274 @enumerate
 275 @item
 276 Take some time to provide an adequate synopsis and description for the
 277 package.  @xref{Synopses and Descriptions}, for some guidelines.
 278
 279 @item
 280 Run @code{guix lint @var{package}}, where @var{package} is the
 281 name of the new or modified package, and fix any errors it reports
 282 (@pxref{Invoking guix lint}).
 283
 284 @item
 285 Make sure the package builds on your platform, using @code{guix build
 286 @var{package}}.
 287
 288 @item
 289 @cindex bundling
 290 Make sure the package does not use bundled copies of software already
 291 available as separate packages.
 292
 293 Sometimes, packages include copies of the source code of their
 294 dependencies as a convenience for users.  However, as a distribution, we
 295 want to make sure that such packages end up using the copy we already
 296 have in the distribution, if there is one.  This improves resource usage
 297 (the dependency is built and stored only once), and allows the
 298 distribution to make transverse changes such as applying security
 299 updates for a given software package in a single place and have them
 300 affect the whole system---something that bundled copies prevent.
 301
 302 @item
 303 Take a look at the profile reported by @command{guix size}
 304 (@pxref{Invoking guix size}).  This will allow you to notice references
 305 to other packages unwillingly retained.  It may also help determine
 306 whether to split the package (@pxref{Packages with Multiple Outputs}),
 307 and which optional dependencies should be used.
 308
 309 @item
 310 For important changes, check that dependent package (if applicable) are
 311 not affected by the change; @code{guix refresh --list-dependent
 312 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
 313
 314 Packages with roughly 100 dependents or more usually have to be
 315 committed to a separate branch.  That branch can then be built
 316 separately by our build farm, and later merged into @code{master} once
 317 everything has been successfully built.  This allows us to fix issues
 318 before they hit users, and to reduce the window during which pre-built
 319 binaries are not available.
 320
 321 @item
 322 @cindex determinism, of build processes
 323 @cindex reproducible builds, checking
 324 Check whether the package's build process is deterministic.  This
 325 typically means checking whether an independent build of the package
 326 yields the exact same result that you obtained, bit for bit.
 327
 328 A simple way to do that is by building the same package several times in
 329 a row on your machine (@pxref{Invoking guix build}):
 330
 331 @example
 332 guix build --rounds=2 my-package
 333 @end example
 334
 335 This is enough to catch a class of common non-determinism issues, such
 336 as timestamps or randomly-generated output in the build result.
 337
 338 Another option is to use @command{guix challenge} (@pxref{Invoking guix
 339 challenge}).  You may run it once the package has been committed and
 340 built by @code{hydra.gnu.org} to check whether it obtains the same
 341 result as you did.  Better yet: Find another machine that can build it
 342 and run @command{guix publish}.  Since the remote build machine is
 343 likely different from yours, this can catch non-determinism issues
 344 related to the hardware---e.g., use of different instruction set
 345 extensions---or to the operating system kernel---e.g., reliance on
 346 @code{uname} or @file{/proc} files.
 347
 348 @item
 349 When writing documentation, please use gender-neutral wording when
 350 referring to people, such as
 351 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
 352 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
 353
 354 @item
 355 Verify that your patch contains only one set of related changes.
 356 Bundling unrelated changes together makes reviewing harder and slower.
 357
 358 Examples of unrelated changes include the addition of several packages,
 359 or a package update along with fixes to that package.
 360
 361 @end enumerate
 362
 363 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
 364 a subject.  You may use your email client or the @command{git
 365 send-email} command.  We prefer to get patches in plain text messages,
 366 either inline or as MIME attachments.  You are advised to pay attention if
 367 your email client changes anything like line breaks or indentation which
 368 could potentially break the patches.