5.3 KiB
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:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
- 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:
curl -sfL https://direnv.net/install.sh | bash
- 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"
- Direnv needs to hook into your shell to work.
You can do this by executing following command. The example below will setup direnv for
-
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:
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.
- When you enter the directory, you'll receive an error message like this:
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:
tea login add
- 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:
- Execute the following command to add your Gitea account locally:
-
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:
git fetch && git rebase origin/main --autostash
- 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.
- Add your changes to Git using
-
Create a Pull Request:
- To automatically open a pull request that gets merged if all tests pass, execute:
merge-after-ci
- 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:
git push origin HEAD:YourUsername-main
- This will directly push to your open pull request.
- If there are issues, fix them and redo step 2. Afterward, execute:
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 placecd ./pkgs/clan-cli pytest -n0 -s --maxfail=1 ./tests/test_nameofthetest.py
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:
nix run .#impure-checks
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:
nix build .#checks.x86_64-linux.clan-pytest --rebuild
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:
import time time.sleep(3600) # Sleep for one hour
-
Use
cntr
andpsgrep
to attach to the Nix sandbox. This allows you to interactively debug your code while it's paused. For example:cntr exec -w your_sandbox_name psgrep -a -x your_python_process_name