Guix science packages
=====================

.. image:: https://guix.bordeaux.inria.fr/jobset/guix-science/badge.svg?type=0
   :target: https://guix.bordeaux.inria.fr/jobset/guix-science

This GNU Guix_ channel provides recent versions of scientific software, which
cannot be included upstream.

See `Specifying Additional Channels`_ in the Guix manual for instructions how
to add it to your installation or simply add the following snippet to your
``channels.scm``:

.. code:: scheme

	(channel
	  (name 'guix-science)
	  (url "https://codeberg.org/guix-science/guix-science.git")
	  (introduction
	   (make-channel-introduction
		"b1fe5aaff3ab48e798a4cce02f0212bc91f423dc"
		(openpgp-fingerprint
		 "CA4F 8CF4 37D7 478F DA05  5FD4 4213 7701 1A37 8446"))))

.. _Guix: https://guix.gnu.org/
.. _Specifying Additional Channels: https://guix.gnu.org/manual/en/guix.html#Specifying-Additional-Channels

Binary substitutes for ``x86_64-linux`` are available from
https://guix.bordeaux.inria.fr, see `Getting Substitutes from Other
Servers`_ in the official manual. The signing key can be imported
using:

.. code:: console

	$ guix archive --authorize <<EOF
    (public-key
     (ecc
      (curve Ed25519)
      (q #89FBA276A976A8DE2A69774771A92C8C879E0F24614AAAAE23119608707B3F06#)))
	EOF

.. _Getting Substitutes from Other Servers: https://guix.gnu.org/manual/en/guix.html#Getting-Substitutes-from-Other-Servers

.. _licensing:

Licensing
---------

Like Guix itself, Guix-Science is distributed under the terms of the `GNU
General Public License`, version 3 or (at your option) any later
version.

A copy of the license is included in the ``COPYING`` file, and each
source file contains an `SPDX header` confirming its license.

Copyright is held by the diverse group of copyright holders for the many
contributions made to Guix-Science over time.

.. _GNU General Public License_: https://www.gnu.org/licenses/gpl-3.0
.. _SPDX header_: https://spdx.dev/learn/handling-license-info/

Contributing
------------

Contributors agree to provide their changes under the same license as
the rest of Guix-Science—see :ref:`licensing`.

We accept software fulfilling the following criteria:

- `Free and open source`_. Use guix-science-nonfree_ otherwise.
- Related to scientific research or teaching.
- Not upstreamable to Guix proper per their rules—e.g., due to excessive
  vendoring.
- Built entirely from source, with the following exceptions:
   1. JavaScript code is allowed to be taken as-is, including
      pre-built/minified JavaScript, as a pragmatic way out of the
      `JavaScript dystopia`;
   2. Packages such as build systems and compilers that have no known
      `bootstrap path` may be built starting from a *binary seed* (a
      pre-built binary of said compiler or build system).

.. _Free and open source: https://opensource.org/osd
.. _guix-science-nonfree: https://codeberg.org/guix-science/guix-science-nonfree
.. _JavaScript dystopia: https://dustycloud.org/blog/javascript-packaging-dystopia/
.. _bootstrap path: https://bootstrappable.org

Submissions of unfinished packaging attempts are welcome as well, as there is
a good chance that others can help finish the work. Please prefix pull requests
for unfinished contributions with WIP.

When obtaining a fresh checkout of this repository, run the following
command:

.. code:: console

          guix git authenticate b1fe5aaff3ab48e798a4cce02f0212bc91f423dc "CA4F 8CF4 37D7 478F DA05  5FD4 4213 7701 1A37 8446"

The command authenticates your checkout and installs Git hooks such that
``git pull`` and ``git push`` automatically authenticate it from there
on.

Hacking this repository
---------------------------------------

Package definitions are stored in ``guix-science/packages/*.scm``,
each ``.scm`` file being a `Guile module`_ containing several package
definitions.

.. _Guile module: https://guix.gnu.org/manual/devel/en/html_node/Package-Modules.html

A new package definition can be added in the relevant module.

For example, after adding a package definition such as:

.. code:: scheme

          (define-public my-package-variable
            (package
              (name "my-package-name")
              ... ))

can be built using the following command:

.. code:: console

          guix build -L /path/to/guix/science/checkout my-package-name

Note that generally the same string is used for the package name and
the Guile variable that points to the package object.

You can learn more about working with a channel in the `Guix manual`_.

.. _Guix manual: https://guix.gnu.org/manual/devel/en/html_node/Creating-a-Channel.html

When submitting a new package or a modification to a package, make sure to run:

.. code:: console

          guix lint -L /path/to/your/guix/science/checkout <package-name>

This repository follows Guix's `Packaging Guidelines`_, refer to them
when contributing.

.. _Packaging Guidelines:
https://guix.gnu.org/manual/devel/en/html_node/Packaging-Guidelines.html

In particular, commit messages follow the `GNU Coding Standards`_ as
in Guix upstream. The title format should be ``module_name: Add
package_name.`` for newly added packages or ``module_name:
package_name: Description.`` for package modifications. The message
should list each modified file, mentioning each modified/added
variable with a description of the modifications.

Please make sure that explanations about the code are included in the
code as comments and not in Git log descriptions.

As a first example, this would be the commit message when adding the
``hello`` package in the ``utils`` module located at
``guix-science/packages/utils.scm``:

.. code:: git

          utils: Add hello.

          * guix-science/packages/utils.scm (hello): New variable.

This would be the commit message when updating the previously added
``hello`` package to version ``1.2.3``:

.. code:: git

          utils: hello: Update to 1.2.3.

          * guix-science/packages/utils.scm (hello): Update to 1.2.3.

Please check this repository's commit log for further examples.

.. _GNU Coding Standards:
https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs

Deprecation policy
---------------------------------------

When a package is broken for more than one month, it can be deprecated
and removed from the repository.

The deprecation mechanism is the following:

- Open an PR removing the deprecated package. **Don't mark it as WIP:**
  so team members are notified.
- Add a **deprecation tag** to the PR.
- Add a **due date** -- one month from the creation of the PR.
- After the due date, if the package has not been fixed, it will be
  effectively removed (the PR will be merged).

 If you maintain another channel depending on Guix-Science, please
 consider joining the ``companion`` team.