Contributing
How to set up a development environment, run the checks, and contribute to Aldwin.
How to set up a development environment, run the checks, and contribute to Aldwin.
Aldwin stays focused on purpose, so a clear contribution matters more than a large one. The package lives in aldwin. This product site is maintained privately; open package issues and pull requests on the aldwin repository.
Aldwin#
Aldwin uses uv and Python 3.11 or newer on macOS or Linux. You also need ripgrep (rg) on your PATH, which the grep tool and its tests use.
git clone https://github.com/lunarstack-co/aldwin.git
cd aldwin
uv sync
uv run aldwin --versionuv sync installs the development dependencies, including optional document libraries, so the whole test suite can run. To try changes by hand, run uv run aldwin.
CI runs these on macOS and Linux against every supported Python version. All must pass before a pull request merges:
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src tests
uv run pytest --cov=aldwin --cov-fail-under=90Use uv run ruff format src tests to fix formatting and uv run ruff check --fix src tests to fix import order. The default test run needs no API keys and makes no network calls. Tests marked live or e2e call real APIs and are for maintainers. Every test uses a temporary home folder, so your real ~/.aldwin is never touched.
The repository's CONTRIBUTING.md covers architecture boundaries, safety rules, Conventional Commits, and how to open a pull request. Issues labelled good first issue are a good place to start.
Some guidelines:
- Keep packages talking in one direction. The CLI never imports
core;corenever importscli,host,client, orprotocol. - Put safety in the policy engine and host, not inside a single tool or the CLI.
- Test new behaviour, including how it fails. Coverage must stay at or above 90%.
- Prefer clarity over cleverness. Type everything. Match the style of the code around your change.
- Avoid new runtime dependencies unless the capability needs them, and keep vendor lock-in out of
core.
Reporting bugs#
Open a GitHub issue with the smallest steps that reproduce the problem, your OS, Python version, and aldwin --version. Use the bug report template when it is there. For a mistake on this site, open an issue on aldwin and say which page URL is wrong.
For a large feature, open an issue to agree the approach before writing code. Ask in issues rather than opening a pull request that needs a product decision.
Reporting vulnerabilities#
Report suspected vulnerabilities privately by emailing contact@lunarstack.co. Do not open a public issue for a security report. Receipt is acknowledged within a few days, and you will be kept posted on the fix.
License#
Aldwin is Apache 2.0 licensed. By contributing, you agree that your contributions are licensed under the same terms.