6ef1eb9ce1
Eval does not stop on the first assertion failure it encouters.
Instead, it tries to evaluate all assertions and returns with a list of
those that failed.
This means our very top `config.mailserver.stateVersion != null`
assertion does not gate against any other assertions trying to compare
null against an integer.
The error prior to this commit can be reproduced by removing
`mailserver.stateVersion = 999;` in tests/lib/config.nix and then trying
to evaluate any of the tests:
~~~bash
# nix eval --raw .#checks.x86_64-linux.internal-unstable
error:
… while evaluating the attribute 'outPath'
at /nix/store/syvnmj3hhckkbncm94kfkbl76qsdqqj3-source/lib/customisation.nix:421:7:
420| drv.drvPath;
421| outPath =
| ^
422| assert condition;
… while calling the 'getAttr' builtin
at «internal»:1:500:
(stack trace truncated; use '--show-trace' to show the full trace)
error: cannot compare null with an integer
~~~
107 lines
3.4 KiB
ReStructuredText
107 lines
3.4 KiB
ReStructuredText
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 != null -> 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.
|