You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

393 lines
15 KiB

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