How to Contribute

Contributions are welcome across documentation, module options, helper packages, tests, themes, compatibility work and every other aspects related to NixKraken.

Development occurs solely on the official GitHub repository.

Before Starting

Do Not Waste Your Time

Please make sure to read the current documentation as a whole before considering to contribute, something you are planning to contribute to may already be available.

Also take a look at currently open issues and pull requests before starting to work on a feature or bug fix, as someone else may already be planning to or has already started working on something similar.

Conform to the Code of Conduct

Read our code of conduct and conform to it in all your interactions with others working on the project. However, do not stress yourself too much over this, everyone can make mistakes as long as they acknowledge and correct them.

Be Polyglot?

NixKraken uses various languages, with the predominant one being the Nix language.

Additionally, we use a fair bit of Bash scripting for helper packages, some Python for automated tests and some HTML, CSS and JavaScript for the documentation.

Contributors are expected to be familiar, to some varying extent, with the following languages and tools, depending on the topic involved:

	Modules	Tests	Pkgs	Themes	Caching	Docs
Nix language	✅	✅	✅	✅	✅	✅
NixOS	✅	✅	┊	┊	┊	┊
nixpkgs	✅	✅	✅	✅	✅	✅
Home Manager	✅	┊	┊	┊	┊	┊
Bash scripting	✅	┊	✅	┊	┊	┊
JSON	✅	┊	✅	┊	┊	┊
jq	✅	┊	┊	┊	┊	┊
GitKraken	✅	✅	✅	┊	┊	┊
Python	┊	✅	┊	┊	┊	┊
Markdown	┊	┊	┊	┊	┊	✅
mdBook	┊	┊	┊	┊	┊	✅
HTML	┊	┊	┊	┊	┊	✅
CSS	┊	┊	┊	┊	┊	✅
JavaScript	┊	┊	┊	┊	┊	✅
Garnix	┊	┊	┊	┊	✅	┊

Although this list could look quite daunting, do not run away yet. You will most likely be doing great just knowing a small bit of any of these, and can only get better at them while working on NixKraken.

Get Familiar with our Git Workflow

As noted in the compatibility section, we use Git tags to publish NixKraken releases.

This process is automated by a Release Please GitHub Actions workflow. Whenever changes that should result in a new release are merged, Release Please will open and maintain a release proposal pull request.

When contributing to NixKraken, you will typically be either:

• adding something new - feat
• fixing something broken - fix

These are the primary Conventional Commits types you will use. Both feat and fix commits are treated as release-relevant changes and will cause Release Please to create or update a release proposal PR.

Once a release proposal PR is merged, the workflow will:

1. Create a new Git tag at the tip of the merged branch
2. Create a corresponding GitHub release

At that point, your changes are available to all NixKraken users.

Typical Contribution Lifecycle

Below is the usual lifecycle of a contribution to NixKraken:

1. Fork the repository
2. Create a new branch for your work (e.g. feat/new-integration or fix/bug-123)
3. Implement your changes on that branch
4. Commit your work as atomic commits, following Conventional Commits specification
5. Open a pull request against the main branch
6. Once your PR is approved and merged, a release proposal PR is created or updated
7. On release proposal PR merge, Release Please will handle tagging and releasing

INFO

We use Cocogitto to enforce Conventional Commits. If your commit messages do not follow the expected format, the checks will fail and you will be asked to adjust them.

To speed up this process, you can use the provided development shell, which includes tooling and Git hooks configured to help you follow the expected commit format.

Repository Layout

Find below a root overview of the repository:

.
├── .github        # GitHub configuration (CI workflows, issue templates, …)
├── .hooks         # Auto Git hooks
├── docs           # Documentation website sources
├── gitkraken      # GitKraken derivations for caching
├── modules        # Module sources
├── pkgs           # Helper packages sources
├── tests          # Module tests
├── themes         # GitKraken themes
├── .envrc         # direnv configuration
├── .prettierrc    # Prettier custom configuration
├── flake.nix      # Root Flake definition
├── garnix.yaml    # Garnix CI configuration
├── module.nix     # Module entrypoint
├── shell.nix      # Nix development shell definition
└── treefmt.nix    # Code style formatters configuration

Admittedly this is a lot, but everything is covered in this documentation, so read along!

Prerequisites

Since NixKraken is mostly written in Nix, it is the only hard requirement. There is however a known constraint on Nix version ≥ 2.4, which is quite old anyway, so you should be good.

Additionally, NixKraken should be compatible with any Nix "flavor" (upstream Nix, Determinate Nix, Lix, Tvix, Snix, …) since it only uses basic Nix capabilities.

Lastly, serving the documentation website locally for development purposes requires mdBook to be available with the following plugins:

• mdbook-alerts
• mdbook-linkcheck
• mdbook-mermaid

Building the documentation website only requires Nix.

Development Generalities

Nix Development Shell

For a better developer experience, NixKraken provides a Nix development shell which source code can be viewed in the shell.nix file.

This development shell does several things:

• add mdBook package and required plugins, for building documentation
• add NodeJS package, for building options reference documentation
• add helper packages, for testing and debugging
• add Cocogitto, for:
  • enforcing conventional commits
  • installing Git hooks

Enabling the development shell can be done in various ways:

# Using new Nix commands
nix develop

# ...or classic Nix commands
nix-shell

# ...or direnv
direnv allow

About direnv

direnv is quite a handy tool which will automatically load the development shell (using classic Nix) when navigating to the project root directory or any of its subdirectories, as long as it is trusted using direnv allow.

TIP

If working on shell.nix, do not forget to run direnv reload to re-apply the development shell, or use tools like lorri to do this automatically for you.

To Flake or Not to Flake?

…that is the question!

The main distribution method for NixKraken is through Flakes. However, we do not want to alienate users who do not use them, nor do we want to force its use on everyone.

For this reason, all Nix code in the repository must be compatible with both Flakes and non Flakes setups, whenever possible.

This means that building any of the tools provided by the project should work either with nix build and nix-build. This also means that all documentation bits should provide instructions for both worlds.