From 366be7d7c05a3b35a25bfcef48382e3b82fc7f40 Mon Sep 17 00:00:00 2001
From: Evgeniy Unzhakov <unzhakov_ev@pnpi.nrcki.ru>
Date: Wed, 29 Apr 2026 22:39:36 +0300
Subject: [PATCH] Create DEVELOPMENT.md

Containts rules and principles of basic development loop for the project
---
 DEVELOPMENT.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 DEVELOPMENT.md

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..dad541d
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,100 @@
+# Development Workflow
+
+## 1. Setup
+
+```bash
+python -m venv .venv
+source .venv/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