103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# Development Workflow
|
|
|
|
## 1. Setup
|
|
|
|
Do not attempt system wide pip installations. Use virtual environment 'sci'.
|
|
Default venv location: `~/.pyenv/`.
|
|
|
|
```bash
|
|
source ~/.pyenv/sci/bin/activate
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## 2. Git Workflow
|
|
|
|
### Before Starting Any Work
|
|
|
|
```bash
|
|
git status # MUST show clean working tree
|
|
git fetch origin
|
|
git rebase origin/main # update to latest main
|
|
```
|
|
|
|
If `git status` is not clean, commit or stash existing changes first. Never begin new work on a dirty working tree.
|
|
|
|
### Branch Strategy
|
|
|
|
```bash
|
|
git checkout main
|
|
git checkout -b dev/<feature-name> # always create a new branch
|
|
```
|
|
|
|
Branch naming: `dev/<short-description>` (e.g., `dev/recoil-correction`)
|
|
|
|
### Merging Rules
|
|
|
|
- All work happens on `dev/*` branches — never commit directly to `main`
|
|
- Tests MUST pass before any merge attempt
|
|
- Merging to `main` requires a pull request with passing CI checks
|
|
- If tests fail, fix them on the dev branch — do NOT merge broken code
|
|
|
|
## 3. Test-Driven Development
|
|
|
|
### TDD Cycle
|
|
|
|
1. **Red** — write a failing test that expresses the desired behavior
|
|
2. **Green** — implement minimal code to make the test pass
|
|
3. **Refactor** — clean up code while keeping all tests green
|
|
|
|
### Test Conventions
|
|
|
|
- Tests live in `tests/` with the same structure as `beta_spectrum/`
|
|
- New component `beta_spectrum/components/foo.py` → test file `tests/test_foo.py`
|
|
- Use shared fixtures from `tests/conftest.py` (`W_low`, `W_mid`, `W_high`, `W_full`, `large_W`)
|
|
- Organize tests in classes by feature area (e.g., `TestComponentBasicProperties`, `TestComponentEdgeCases`)
|
|
- Each test class should have a docstring explaining what is being tested and why
|
|
- Use descriptive test names: `test_threshold_vanishes`, not `test_1`
|
|
|
|
### What to Test
|
|
|
|
- **Physical constraints**: values at thresholds, endpoints, and boundaries must match known physics
|
|
- **Monotonicity / positivity**: spectrum components should not produce unphysical negative values
|
|
- **Shape correctness**: output shape must match input shape
|
|
- **Type safety**: components accept and return `np.ndarray`
|
|
- **Numerical stability**: no NaN or inf in the physical energy range (except where physically expected)
|
|
|
|
## 4. Quality Gates
|
|
|
|
All of the following MUST pass before merging to `main`:
|
|
|
|
```bash
|
|
pytest # all tests pass
|
|
black --check . # code formatting
|
|
ruff check . # linting
|
|
mypy . # type checking (strict mode)
|
|
```
|
|
|
|
These are configured in `pyproject.toml`. Run them individually to identify failures.
|
|
|
|
## 5. Agent Instructions
|
|
|
|
When working on this project, agents must:
|
|
|
|
1. **Read existing tests first** — understand patterns before writing new ones
|
|
2. **Follow existing conventions** — match test style, fixture usage, and class organization
|
|
3. **Never commit changes** without explicit user request
|
|
4. **Never merge branches** without explicit user request
|
|
5. **Verify `git status` is clean** before starting any file modifications
|
|
6. **Work on a dev branch** — create `dev/<description>` and switch to it
|
|
7. **Run quality gates** after making changes and report results
|
|
8. **Update docs** when changing public API or adding features
|
|
|
|
## 6. Release Checklist
|
|
|
|
- [ ] All tests pass (`pytest`)
|
|
- [ ] Code is formatted (`black --check`)
|
|
- [ ] No lint errors (`ruff check`)
|
|
- [ ] Type checks pass (`mypy`)
|
|
- [ ] Update version in `pyproject.toml`
|
|
- [ ] Update `Development Status` section in `README.md`
|
|
- [ ] Commit changes
|
|
- [ ] Create git tag: `git tag v<version>`
|
|
- [ ] Push to remote
|