7.0 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:
- To automatically setup a devshell on entering the directory
nix profile install nixpkgs#nix-direnv-flakes
- To automatically setup a devshell on entering the directory
-
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
-
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
-
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? No
- Username: YourUsername
- Password: YourPassword
- Set Optional settings: No
- URL of Gitea instance:
- Execute the following command to add your Gitea account locally:
-
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:
-
(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
- To syntax check your code you can run:
-
Open a Pull Request:
- To automatically open up a pull request you can use our tool called:
merge-after-ci --reviewers Mic92 Lassulus Qubasa
Debugging
Here are some methods for debugging and testing the clan-cli:
See all possible packages and tests
To quickly show all possible packages and tests execute:
nix flake show --system no-eval
Under checks
you will find all tests that are executed in our CI. Under packages
you find all our projects.
git+file:///home/lhebendanz/Projects/clan-core
├───apps
│ └───x86_64-linux
│ ├───install-vm: app
│ └───install-vm-nogui: app
├───checks
│ └───x86_64-linux
│ ├───borgbackup omitted (use '--all-systems' to show)
│ ├───check-for-breakpoints omitted (use '--all-systems' to show)
│ ├───clan-dep-age omitted (use '--all-systems' to show)
│ ├───clan-dep-bash omitted (use '--all-systems' to show)
│ ├───clan-dep-e2fsprogs omitted (use '--all-systems' to show)
│ ├───clan-dep-fakeroot omitted (use '--all-systems' to show)
│ ├───clan-dep-git omitted (use '--all-systems' to show)
│ ├───clan-dep-nix omitted (use '--all-systems' to show)
│ ├───clan-dep-openssh omitted (use '--all-systems' to show)
│ ├───"clan-dep-python3.11-mypy" omitted (use '--all-systems' to show)
├───packages
│ └───x86_64-linux
│ ├───clan-cli omitted (use '--all-systems' to show)
│ ├───clan-cli-docs omitted (use '--all-systems' to show)
│ ├───clan-ts-api omitted (use '--all-systems' to show)
│ ├───clan-vm-manager omitted (use '--all-systems' to show)
│ ├───default omitted (use '--all-systems' to show)
│ ├───deploy-docs omitted (use '--all-systems' to show)
│ ├───docs omitted (use '--all-systems' to show)
│ ├───editor omitted (use '--all-systems' to show)
└───templates
├───default: template: Initialize a new clan flake
└───new-clan: template: Initialize a new clan flake
You can execute every test separately by following the tree path nix build .#checks.x86_64-linux.clan-pytest
for example.
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:psgrep -a -x your_python_process_name cntr attach <container id, container name or process id>
Or you can also use the nix breakpoint hook
Standards
- Every new module name should be in kebab-case.
- Every fact definition, where possible should be in kebab-case.