nixos-mailserver/docs/howto-develop.rst

Contribute or troubleshoot
==========================

To report an issue, please go to
`<https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/issues>`_.

If you have questions, feel free to reach out:

* Matrix: `#nixos-mailserver:nixos.org <https://matrix.to/#/#nixos-mailserver:nixos.org>`__
* IRC: `#nixos-mailserver <ircs://irc.libera.chat/nixos-mailserver>`__ on `Libera Chat <https://libera.chat/guides/connect>`__

All our workflows rely on Nix being configured with `Flakes <https://wiki.nixos.org/wiki/Flakes#Installing_flakes>`__.

Development Shell
-----------------

We provide a `flake.nix` devshell that automatically sets up pre-commit hooks,
which allows for fast feedback cycles when making changes to the repository.


::

  $ nix develop


We recommend setting up `direnv <https://direnv.net/>`__ to automatically
attach to the development environment when entering the project directories.

Run NixOS tests
---------------

To run the test suite, you need to enable `Nix Flakes
<https://wiki.nixos.org/wiki/Flakes#Installing_flakes>`__.

You can then run the testsuite via

::

   $ nix flake check -L

Since Nix doesn't garantee your machine have enough resources to run
all test VMs in parallel, some tests can fail. You would then haev to
run tests manually. For instance:

::

   $ nix build .#hydraJobs.x86_64-linux.external-unstable -L


Contributing to the documentation
---------------------------------

The documentation is written in RST (except option documentation which is in CommonMark),
built with Sphinx and published by `Read the Docs <https://readthedocs.org/>`_.

For the syntax, see the `RST/Sphinx primer
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.

To build the documentation, you need to enable `Nix Flakes
<https://wiki.nixos.org/wiki/Flakes#Installing_flakes>`__.


::

   $ nix build .#documentation
   $ xdg-open result/index.html


Manual migrations
-----------------

We need to take great care around providing a migration story around breaking
changes. If manual intervention becomes necessary we provide the `stateVersion`
option to notify the user that they need to complete a migration before
they can deploy an update.

If that is the case for your change, find the highest `stateVersion` that is
being asserted on in `mail-server/assertions.nix`. Then pick the next number
and add a new assertion, write a good summary describing the issue and what
remediation steps are necessary. Finally reference the URL to the specific
section on the migration page in the documentation.

.. code-block:: nix

  {
    assertions = [
      {
        assertion = config.mailserver.stateVersion < 1;
        message = ''
          Problem: The home directory for the foobar service is snafu.
          Remediation:
            - Stop the `foobar.service`
            - Rename `/var/lib/foobaz` to `/var/lib/foobar`
            - Increase the `mailserver.stateVersion` to 1.

          Check https://nixos-mailserver.readthedocs.io/en/latest/migrations.html#specific-anchor-here for further details.
        '';
      }
    ];
  }

The setup guide should always reference the latest `stateVersion`, since we
don't require any migration steps for new setups.

The migration documentation should paint a more complete picture about the steps
that need to be carried out and why this has become necessary. Make sure to
reference the correct anchor in the URL you put into the assertion message.