# Contributing

For a full developer guide including test overview, CI workflow details, and release PR process, see the [Developer Guide](README.md#developer-guide) section in the README.
For maintainer-oriented PR/release/tap runbooks, see [docs/maintainer-playbook.md](docs/maintainer-playbook.md).

## Dev Setup

```bash
pip install uv
uv venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
uv pip install -e ".[dev,all]"
```

## Lint

```bash
ruff check .
ruff format .
```

## Test

```bash
# Fast unit/smoke tests (no coverage; matches CI smoke lane)
pytest -m "not integration and not slow" -o addopts=

# Full suite with coverage
pytest --cov=foldermix tests/

# Integration/snapshot tests (no coverage; matches CI smoke lane)
pytest -m integration -o addopts=
```

### Cross-Platform Policy Integration Suite

```bash
pytest tests/integration/test_policy_packs.py tests/integration/test_policy_cross_platform.py \
  -m integration -o addopts="-vv -ra --strict-markers --strict-config"
```

This suite is also executed on Linux/macOS/Windows in CI (`policy-integration-matrix` job).

### Policy Matrix Failure Triage (Path/Newline/Encoding)

When the cross-platform policy integration lane fails:

1. Re-run the policy integration suite locally with `-o addopts=` to remove coverage noise.
2. Check fixture drift:
   - `tests/integration/fixtures/expected/policy_pack_deltas.json`
   - `tests/integration/fixtures/expected/policy_cross_platform_summary.json`
3. Confirm path normalization remains POSIX-style in findings (for example `nested folder/space name.txt`).
4. Confirm newline/encoding edge files are generated by test helpers:
   - CRLF bytes for `windows_newlines.txt`
   - Latin-1 bytes for `latin1.txt`
5. If behavior changes intentionally, regenerate expected snapshots in the same PR and note why in the PR body.

## Mutation Test

```bash
pip install -e ".[dev,mutation,all]"
python -m mutmut run
python -m mutmut results
```

## Performance Smoke Test

```bash
FOLDERMIX_RUN_PERF_SMOKE=1 python -m pytest tests/test_perf_smoke.py -q -o addopts=
```

## Release PR Process

1. Bump `version` in `pyproject.toml`.
2. If packer output changed, regenerate snapshot fixtures in `tests/integration/fixtures/expected/` and commit them in the same PR.
3. Run `pytest --cov=foldermix tests/` locally and confirm all tests pass.
4. Open a PR targeting `main`; merge once all CI jobs pass.

On merge, `publish-pypi` detects the version bump and publishes to PyPI automatically; `update-homebrew-tap` then updates the Homebrew formula.

See the [Release PR Process](README.md#release-pr-process) section in the README for the full checklist.

## Homebrew Release Automation

On `main` pushes that bump `pyproject.toml` version:

1. `publish-pypi` publishes to PyPI (OIDC trusted publisher).
2. `update-homebrew-tap` renders `Formula/foldermix.rb` and pushes it to the tap repo.

Required one-time setup:

- Create tap repo: `foldermix/homebrew-foldermix`.
- Add Actions secret in this repo:
  - `HOMEBREW_TAP_GITHUB_TOKEN`: classic PAT (or fine-grained token) with write access to the tap repo.

Policy note:

- The Homebrew formula intentionally ships the core dependency set.
- Optional converter extras are documented as Python-tool installs (`uv tool`, `pipx`, or virtualenv pip) in the README installation section.

## Maintainer PR Checklist

Use [docs/maintainer-playbook.md](docs/maintainer-playbook.md) as the canonical operational runbook. Before merge:

1. CI checks are green (or intentionally skipped by workflow design).
2. Unresolved PR comments/threads are triaged; already-addressed items are resolved.
3. Patch/new-line coverage expectations for the PR are satisfied (target 100% when explicitly requested).
4. Snapshot fixtures are updated in the same PR when behavior changes.
5. PR description clearly captures behavior changes and validation evidence.

## AI Coding Agent Guide

See [docs/agents.md](docs/agents.md) for a detailed orientation for AI coding agents working on this repository.
