Contributing
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:
-
Install Nix Package Manager:
-
You can install the Nix package manager by either downloading the Nix installer or running this command:
-
Install direnv:
-
Download the direnv package from here or run the following command:
-
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
andbash
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && eval "$SHELL"
-
Clone the Repository and Navigate:
-
Clone this repository and navigate to it.
-
Allow .envrc:
-
When you enter the directory, you'll receive an error message like this:
- Execute
direnv allow
to automatically execute the shell script.envrc
when entering the directory.
Setting Up Your Git Workflow
Let's set up your Git workflow to collaborate effectively:
-
Register Your Gitea Account Locally:
-
Execute the following command to add your Gitea account locally:
-
Fill out the prompt as follows:
- URL of Gitea instance:
https://git.clan.lol
- Name of new Login [gitea.gchq.icu]:
gitea.gchq.icu:7171
- Do you have an access token? No
- Username: YourUsername
- Password: YourPassword
- Set Optional settings: No
- URL of Gitea instance:
-
Git Workflow:
-
Add your changes to Git using
git add <file1> <file2>
. - Run
nix fmt
to lint your files. - Commit your changes with a descriptive message:
git commit -a -m "My descriptive commit message"
. - Make sure your branch has the latest changes from upstream by executing:
- Use
git status
to check for merge conflicts. - If conflicts exist, resolve them. Here's a tutorial for resolving conflicts in VSCode.
-
After resolving conflicts, execute
git merge --continue
and repeat step 5 until there are no conflicts. -
Create a Pull Request:
-
To automatically open a pull request that gets merged if all tests pass, execute:
-
Review Your Pull Request:
-
Visit https://git.clan.lol and go to the project page. Check under "Pull Requests" for any issues with your pull request.
-
Push Your Changes:
- If there are issues, fix them and redo step 2. Afterward, execute:
- This will directly push to your open pull request.
Debugging
Here are some methods for debugging and testing the clan-cli:
Test Locally in Devshell with Breakpoints
To test the cli locally in a development environment and set breakpoints for debugging, follow these steps:
- Run the following command to execute your tests and allow for debugging with breakpoints:
You can place
breakpoint()
in your Python code where you want to trigger a breakpoint for debugging.
Test Locally in a Nix Sandbox
To run tests in a Nix sandbox, you have two options depending on whether your test functions have been marked as impure or not:
Running Tests Marked as Impure
If your test functions need to execute nix build
and have been marked as impure because you can't execute nix build
inside a Nix sandbox, use the following command:
This command will run the impure test functions.
Running Pure Tests
For test functions that have not been marked as impure and don't require executing nix build
, you can use the following command:
This command will run all pure test functions.
Inspecting the Nix Sandbox
If you need to inspect the Nix sandbox while running tests, follow these steps:
- Insert an endless sleep into your test code where you want to pause the execution. For example:
- Use
cntr
andpsgrep
to attach to the Nix sandbox. This allows you to interactively debug your code while it's paused. For example:
Standards
Every new module name should be in kebab-case. Every fact definition, where possible should be in kebab-case.