Thanks for your interest in contributing to Ascender. This document covers the development setup, testing, and pull request guidelines.
Fork and clone the repository:
git clone https://github.com/<your-user>/ascender.git
cd ascenderBring up the containerised development environment:
make docker-composeSee docs/development/docker.md for the full walkthrough, and kind.md or minikube.md for cluster-based alternatives.
Add the main repository as a second remote, so you can rebase onto it later:
git remote add upstream https://github.com/ctrliq/ascender.gitEvery pull request runs the checks in
.github/workflows/ci.yml. Run the ones your
change can affect before pushing, in the development environment, and run the
whole API suite rather than only the tests you touched: a new setting, for
example, fails a test in ascender/conf/tests/ that no logging test exercises.
docker exec tools_ascender_1 bash -c "cd /ascender_devel && make test"make test is what CI's api-test job runs. It covers every directory in
TEST_DIRS and then runs ascender-manage check_migrations and
ascender-manage check_settings. The lint, type-check and UI jobs, and the
command for each, are listed in
.github/copilot-instructions.md.
Configuration lives in pyproject.toml and tox.ini.
A setting registered in ascender/main/conf.py or ascender/conf/conf.py
needs more than the registration, and CI checks each part:
| Change | Checked by |
|---|---|
Add it to ascender/settings/typed.py (ascender-manage generate_setting_types writes the file) |
ascender/conf/tests/functional/test_setting_types.py |
Regenerate ascender/ui/src/types/api.generated.ts with make ui-api-types and commit it |
ui-api-types-drift |
| Give it a default its own field accepts | ascender-manage check_settings |
Also:
- Set
min_valueandmax_valueto the range the setting's consumer accepts. A value rsyslog or the kernel ignores passes validation and then silently does nothing. Test that out-of-range values are rejected and that a non-default value reaches the consumer. - A
LOG_AGGREGATOR_*setting also needs a default inascender/settings/defaults.py. The rsyslog configurer clears its cached values by the namesdir(settings)returns, which are the database rows and the file defaults, so a reverted setting with no file default keeps its old value.
Create a feature branch from main:
git checkout -b my-feature mainmain requires a linear history. To pick up changes from main, or to
resolve a conflict, rebase onto it rather than merging it in:
git fetch upstream
git rebase upstream/main
git push --force-with-leaseWrite clear, concise commit messages:
Short summary (under 72 characters)
Longer description of what changed and why, if needed.
related #123
Reference the issue a change addresses with related #nnn, in the commit
message and the PR description, as the
pull request template asks. Maintainers
close the issue themselves.
Every commit must be signed off, certifying the terms in DCO_1_1.md:
git commit -s -m "Short summary"- Make sure the checks above pass locally.
- One logical change per PR. Do not bundle unrelated fixes.
- Target the
mainbranch. - Explain what changed and why in the PR description.
- For the template's ASCENDER VERSION, run
make VERSIONinside the development container. On a host withoutsetuptools-scmit prints onlyawx:.
CI on a pull request from a fork waits until a maintainer approves the run.
Open an issue at github.com/ctrliq/ascender/issues. Include the version you are running and the steps that reproduce the problem.
For security vulnerabilities, follow SECURITY.md instead of opening a public issue.