Contributing

Contributing to Clan

Continuous Integration (CI): Each pull request gets automatically tested by gitea. If any errors are detected, it will block pull requests until they're resolved.

Dependency Management: We use the Nix package manager to manage dependencies and ensure reproducibility, making your development process more robust.

Supported Operating Systems

  • Linux
  • macOS

Getting Started with the Development Environment

Let's get your development environment up and running:

  1. Install Nix Package Manager:

    • You can install the Nix package manager by either downloading the Nix installer or running this command:

      curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/nix-installer | sh -s -- install

  2. Install direnv:

    • To automatically setup a devshell on entering the directory

      nix profile add nixpkgs#nix-direnv nixpkgs#direnv

  3. Add direnv to your shell:

    • direnv needs to hook into your shell to work. You can do this by executing following command. The example below will setup direnv for zsh and bash

      echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"

  4. Allow the devshell

    • Go to clan-core/pkgs/clan-cli and do a direnv allow to setup the necessary development environment to execute the clan command

  5. Create a Gitea Account

    • Register an account on git.clan.lol

    • Fork the clan-core repository

    • Clone the repository and navigate to it

    • Add a new remote called upstream

      git remote add upstream gitea@git.clan.lol:clan/clan-core.git

  6. Allow .envrc

    • When you enter the directory, you'll receive an error message like this:

      direnv: error .envrc is blocked. Run `direnv allow` to approve its content

    • Execute direnv allow to automatically execute the shell script .envrc when entering the directory.

  7. (Optional) Install git Hooks

    • To syntax check your code you can run:

      nix fmt

    • To make this automatic install the git hooks

      ./scripts/pre-commit

If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup.

For instance, if you need to update nixos-anywhere in clan-cli, find its usage:

run(
    nix_shell(
        ["nixos-anywhere"],
        cmd,
    ),
    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
)

You can replace "nixpkgs#nixos-anywhere" with your local path:

run(
    nix_shell(
        ["<path_to_local_src>#nixos-anywhere"],
        cmd,
    ),
    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
)

The <path_to_local_src> doesn't need to be a local path, it can be any valid flakeref. And thus can point to test already opened PRs for example.

Standards

  • Every new module name should be in kebab-case.
  • Every vars definition, where possible should be in kebab-case.
  • Command line help descriptions should start capitalized and should not end in a period.

Documentation Style Guidelines

Please refer to our Style Guide for Documentation and Blog Posts when writing documentation.