Contributing
We welcome contributions to Asymmetry!
Development setup
Fork the repository on GitHub
Clone your fork:
git clone https://github.com/your-username/asymmetry.git cd asymmetry
Install in development mode:
pip install -e ".[dev]"
Create a branch for your changes:
git checkout -b feature-name
Code style
We use:
ruff for linting and formatting
Type hints for function signatures
Docstrings in NumPy or Google style
Run checks:
ruff check src/
ruff format src/
Testing
Write tests for new features using pytest:
pytest tests/
Ensure all tests pass before submitting.
Documentation
Update documentation for any new features:
Add docstrings to new functions/classes
Update user guide if needed
Build docs locally to check:
python3 tools/harness.py docs --mode source open docs/_build/html/index.html
Source mode needs no private corpus, capture, or inventory network access. Registered missing screenshots appear as Optional generated screenshot notices. The gate rejects malformed markup, broken or ambiguous authored local/API links, unknown images, missing static/download assets, and other Sphinx warnings. Named external objects may remain unlinked, and automatic annotation hyperlinks are not generated; parameter and return descriptions remain readable.
For publishing, prepare ordinary GUI captures and any permitted labelled corpus
placeholders, then run python3 tools/harness.py docs --mode publish. This
uses the same defect gate and also requires complete ordinary GUI assets.
A limited source build does not certify publishing readiness. Both modes reread
all sources, preserve build failures, and enforce a 600 KB HTML page budget.
Pull request process
Ensure tests pass and code is formatted
Update CHANGELOG.md
Push to your fork
Open a pull request with a clear description
Reporting issues
Use the issue forms to record work that can be implemented and checked independently. Implementation captures the outcome, evidence, scope, decisions, compatibility, acceptance criteria, validation, and documentation. List prerequisites under Blocked by and start dependent work only when each is closed as completed. For two PRs, the first references the issue and the final PR closes it.
Instrument review captures the instrument, version reviewed, sections checked, findings, and supporting evidence. Choose Do not name me to withhold consent for naming you in the published review record. The issue and GitHub account remain public; a maintainer can file on a reviewer’s behalf. Consent can be changed by commenting.
For issues filed through the CLI or API, use the form’s field labels as third-level headings, in order.
Code of Conduct
Be respectful and inclusive. We follow the Python Community Code of Conduct.
Released project compatibility
Keep versioned project and standalone wizard converters, with synthetic fixtures matching emitted released shapes, permanently. This includes alpha releases. Remove runtime repair after conversion is owned by persistence and current producers emit canonical state. Check parameter curves independently of JSON round trips; preserve draft forms, unavailable user models, and captured execution attribution. A storage version never proves that a historical calculation is current.