Imported from gencau/test-practices-agent-configurations (
dataset/repos/sixty-north§cosmic-ray/AGENTS.md). Install upstream withnpx skills add gencau/test-practices-agent-configurations --skill sixty-north§cosmic-ray. Copyright stays with the author.
Repository Guidelines
Revision control
If there is a .jj directory or otherwise appears that jujutsu is being used for verison control, use it instead of git.
Project Structure & Module Organization
Cosmic Ray follows a src/ layout: packages live in src/cosmic_ray, metadata in src/cosmic_ray/version.py, and CLI surfaces in src/cosmic_ray/cli. Tests live in tests/unittests, tests/tools, and tests/e2e, with fixtures/configs parked under tests/resources. Documentation resides in docs/source, and helper utilities live in tools/. The canonical upstream is https://github.com/sixty-north/cosmic-ray; match this layout when mirroring across forks.
Build, Test, and Development Commands
python -m venv .venv && source .venv/bin/activateisolates dependencies before syncing/installing.pip install -e .[dev](oruv sync --dev) installs the CLI plus dev tooling.pytestruns the default suite;pytest --run-slow tests/e2eadds the long mutation workflows.ruff check src tests(optionally--fix) keeps linting/ordering consistent.
Coding Style & Naming Conventions
Target idiomatic Python 3.9+ and PEP 8, but favor clarity when a rule conflicts with readability. ruff enforces a 120-character limit and isort-style grouping; let it rewrite imports instead of hand-tuning. CI expects uv ruff . and uv ruff format . before every commit. Modules stay snake_case, classes use CapWords, and CLI flags remain kebab-case (cosmic-ray exec). Keep shared configuration (*.conf, pyproject.toml) in the repo root or tests/resources so tooling can load them without extra paths.
Testing Guidelines
Pytest backs every layer: unit coverage in tests/unittests, tool coverage in tests/tools, and slow integration runs in tests/e2e. Name files test_<feature>.py, keep test functions descriptive, and centralize fixtures in tests/conftest.py. Tag long-lived scenarios with @pytest.mark.slow so contributors can opt in via --run-slow. Add regression tests whenever you alter a mutation operator, CLI flag, or persistence layer.
Commit & Pull Request Guidelines
Follow the format from CONTRIBUTING.rst: subjects are imperative and reference an issue (Issue #1234 - Make operator ordering deterministic) or start with Doc - for prose-only commits. Commit bodies should state problem, impact, and fix. Before opening a PR, run git diff --check, ruff check, and the relevant pytest targets; summarize those results plus reproduction steps (and screenshots/logs for reporting tools such as cr-html) in the PR description. Keep PRs focused and call out dependency or configuration changes in pyproject.toml.
Security & Configuration Tips
Do not commit plaintext secrets—deploy_key.enc shows the expected encrypted form. Store experimental configs under tests/resources or ignore them locally. When developing HTTP distributors or remote workers, prefer the mocked services in tests/tools and document any new ports, certificates, or environment variables directly in the pull request.