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://install.determinate.systems/nix | sh -s -- install
     

2. Install direnv:

   • To automatically setup a devshell on entering the directory

     nix profile install nixpkgs#nix-direnv-flakes 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 https://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. Create an access token:

   • Log in to Gitea.
   • Go to your account settings.
   • Navigate to the Applications section.
   • Click Generate New Token.
   • Name your token and select all available scopes.
   • Generate the token and copy it for later use.
   • Your access token is now ready to use with all permissions.

7. Register Your Gitea Account Locally:

   • Execute the following command to add your Gitea account locally:

     tea login add
     

   • Fill out the prompt as follows:
     • URL of Gitea instance: https://git.clan.lol
     • Name of new Login [git.clan.lol]:
     • Do you have an access token? Yes
     • Token:
     • Set Optional settings: No

8. 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.

9. (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
     

10. Open a Pull Request:

    • To automatically open up a pull request you can use our tool called:

      merge-after-ci --reviewers Mic92 Lassulus Qubasa
      

Related Projects

• Data Mesher: dm
• Nixos Facter: nixos-facter
• Nixos Anywhere: nixos-anywhere
• Disko: disko

Fixing Bugs or Adding Features in Clan-CLI

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(
        ["nixpkgs#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),
)

Standards

• Every new module name should be in kebab-case.
• Every fact definition, where possible 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.