;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2014, 2015, 2016, 2017 Manolis Fragkiskos Ragkousis ;;; Copyright © 2018 Ludovic Courtès ;;; ;;; This file is part of GNU Guix. ;;; ;;; GNU Guix is free software; you can redistribute it and/or modify it ;;; under the terms of the GNU General Public License as published by ;;; the Free Software Foundation; either version 3 of the License, or (at ;;; your option) any later version. ;;; ;;; GNU Guix is distributed in the hope that it will be useful, but ;;; WITHOUT ANY WARRANTY; without even the implied warranty of ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;;; GNU General Public License for more details. ;;; ;;; You should have received a copy of the GNU General Public License ;;; along with GNU Guix. If not, see . (define-module (gnu packages hurd) #:use-module (guix licenses) #:use-module (guix download) #:use-module
aboutsummaryrefslogtreecommitdiff
@node Contributing
@chapter Contributing

This project is a cooperative effort, and we need your help to make it
grow!  Please get in touch with us on @email{guix-devel@@gnu.org} and
@code{#guix} on the Libera Chat IRC network.  We welcome ideas, bug
reports, patches, and anything that may be helpful to the project.  We
particularly welcome help on packaging (@pxref{Packaging Guidelines}).

@cindex code of conduct, of contributors
@cindex contributor covenant
We want to provide a warm, friendly, and harassment-free environment, so
that anyone can contribute to the best of their abilities.  To this end
our project uses a ``Contributor Covenant'', which was adapted from
@url{https://contributor-covenant.org/}.  You can find a local version in
the @file{CODE-OF-CONDUCT} file in the source tree.

Contributors are not required to use their legal name in patches and
on-line communication; they can use any name or pseudonym of their
choice.

@menu
* Requirements::                Software needed to build and run Guix.
* Building from Git::           The latest and greatest.
* Running the Test Suite::      Testing Guix.
* Running Guix Before It Is Installed::  Hacker tricks.
* The Perfect Setup::           The right tools.
* Alternative Setups::          Other possible tools that do the job.
* Source Tree Structure::       Source code guided tour.
* Packaging Guidelines::        Growing the distribution.
* Coding Style::                Hygiene of the contributor.
* Submitting Patches::          Share your work.
* Tracking Bugs and Changes::   Keeping it all organized.
* Teams::                       Coordinating efforts.
* Making Decisions::            Collectively choosing the way forward.
* Commit Access::               Pushing to the official repository.
* Reviewing the Work of Others::  Some guidelines for sharing reviews.
* Updating the Guix Package::   Updating the Guix package definition.
* Deprecation Policy::          Commitments and tools for deprecation.
* Writing Documentation::       Improving documentation in GNU Guix.
* Translating Guix::            Make Guix speak your native language.
* Contributing to Guix's Infrastructure::  Make Guix ecosystem work better.
@end menu

@node Requirements
@section Requirements

You can easily hack on Guix itself using Guix and Git, which we use for
version control (@pxref{Building from Git}).

But when packaging Guix for foreign distros or when bootstrapping on
systems without Guix, and if you decide to not just trust and install
our readily made binary (@pxref{Binary Installation}), you can download
a release version of our reproducible source tarball and read on.

This section lists requirements when building Guix from source.  The
build procedure for Guix is the same as for other GNU software, and is
not covered here.  Please see the files @file{README} and @file{INSTALL}
in the Guix source tree for additional details.

@cindex official website
GNU Guix is available for download from its website at
@url{https://www.gnu.org/software/guix/}.

GNU Guix depends on the following packages:

@itemize
@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
version 3.0.3 or later;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
Preparations, how to install the GnuTLS bindings for Guile,,
gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
until version 3.7.8 included.};
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
version 0.1.0 or later;
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@item
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
or later;
@item @uref{https://git-scm.com, Git} (yes, both!);
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
4.3.0 or later;
@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize

The following dependencies are optional:

@itemize
@item
@c Note: We need at least 0.13.0 for #:nodelay.
Support for build offloading (@pxref{Daemon Offload Setup}) and
@command{guix copy} (@pxref{Invoking guix copy}) depends on
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
version 0.13.0 or later.

@item
@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
compression and decompression in @command{guix publish} and for
substitutes (@pxref{Invoking guix publish}).

@item
@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
the @code{crate} importer (@pxref{Invoking guix import}).

@item
@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
the @code{go} importer (@pxref{Invoking guix import}) and for some of
the ``updaters'' (@pxref{Invoking guix refresh}).

@item
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
@end itemize

Unless @option{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:

@itemize
@item @url{https://gnupg.org/, GNU libgcrypt};
@item @url{https://sqlite.org, SQLite 3};
@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize

@node Building from Git
@section Building from Git

If you want to hack Guix itself, it is recommended to use the latest
version from the Git repository:

@example
git clone https://git.savannah.gnu.org/git/guix.git
@end example

@cindex authentication, of a Guix checkout
How do you ensure that you obtained a genuine copy of the repository?
To do that, run @command{guix git authenticate}, passing it the commit
and OpenPGP fingerprint of the @dfn{channel introduction}
(@pxref{Invoking guix git authenticate}):

@c The commit and fingerprint below must match those of the channel
@c introduction in '%default-channels'.
@example
git fetch origin keyring:keyring
guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@noindent
This command completes with exit code zero on success; it prints an
error message and exits with a non-zero code otherwise.

As you can see, there is a chicken-and-egg problem: you first need to
have Guix installed.  Typically you would install Guix System
(@pxref{System Installation}) or Guix on top of another distro
(@pxref{Binary Installation}); in either case, you would verify the
OpenPGP signature on the installation medium.  This ``bootstraps'' the
trust chain.

The easiest way to set up a development environment for Guix is, of
course, by using Guix!  The following command starts a new shell where
all the dependencies and appropriate environment variables are set up to
hack on Guix:

@example
guix shell -D guix -CPW
@end example

or even, from within a Git worktree for Guix:

@example
guix shell -CPW
@end example

If @option{-C} (short for @option{--container}) is not supported on your
system, try @command{--pure} instead of @option{-CPW}.
@xref{Invoking guix shell}, for more information on that command.

If you are unable to use Guix when building Guix from a checkout, the
following are the required packages in addition to those mentioned in the
installation instructions (@pxref{Requirements}).

@itemize
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
@item @url{https://gnu.org/software/automake/, GNU Automake};
@item @url{https://gnu.org/software/gettext/, GNU Gettext};
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
@item @url{https://www.graphviz.org/, Graphviz};
@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize

On Guix, extra dependencies can be added by instead running @command{guix
shell}:

@example
guix shell -D guix help2man git strace --pure
@end example

From there you can generate the build system infrastructure
using Autoconf and Automake:

@example
./bootstrap
@end example

If you get an error like this one:

@example
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@end example

@noindent
it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
provided by pkg-config.  Make sure that @file{pkg.m4} is available.  The
same holds for the @file{guile.m4} set of macros provided by Guile.  For
instance, if you installed Automake in @file{/usr/local}, it wouldn’t
look for @file{.m4} files in @file{/usr/share}.  In that case, you have
to invoke the following command:

@example
export ACLOCAL_PATH=/usr/share/aclocal
@end example

@xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
more information.

@cindex state directory
@cindex localstatedir
@cindex system configuration directory
@cindex sysconfdir
Then, run:

@example
./configure
@end example

@noindent
Optionally, @code{--localstatedir} and @code{--sysconfdir} can also be
provided as arguments.  By default, @code{localstatedir} is @file{/var}
(@pxref{The Store}, for information about this) and @code{sysconfdir} is
@file{/etc}.  Note that you will probably not run @command{make install}
at the end (you don't have to) but it's still important to pass the
right @code{localstatedir} and @code{sysconfdir} values, which get
recorded in the @code{(guix config)} Guile module.

Finally, you can build Guix and, if you feel so inclined, run the tests
(@pxref{Running the Test Suite}):

@example
make
make check
@end example

@noindent
If anything fails, take a look at installation instructions
(@pxref{Installation}) or send a message to the
@email{guix-devel@@gnu.org, mailing list}.

From there on, you can authenticate all the commits included in your
checkout by running:

@example
guix git authenticate \
  9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

The first run takes a couple of minutes, but subsequent runs are faster.
On subsequent runs, you can run the command without any arguments since
the @dfn{introduction} (the commit ID and OpenPGP fingerprints above)
will have been recorded@footnote{This requires a recent version of Guix,
from May 2024 or more recent.}:

@example
guix git authenticate
@end example

When your configuration for your local Git repository doesn't match
the default one, you can provide the reference for the @code{keyring}
branch @i{via} the @option{-k} option.  The following
example assumes that you have a Git remote called @samp{myremote}
pointing to the official repository:

@example
guix git authenticate \
  -k myremote/keyring \
  9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@xref{Invoking guix git authenticate}, for more information on this
command.

@quotation Note
By default, hooks are installed such that @command{