# Contributing to NORA

Thank you for your interest in contributing to NORA!

## Developer Certificate of Origin (DCO)

By submitting a pull request, you agree to the [Developer Certificate of Origin](https://developercertificate.org/).
Your contribution will be licensed under the [MIT License](LICENSE).

You confirm that you have the right to submit the code and that it does not violate any third-party rights.

## Scope, assignment and incentives

- **Issues are not assigned.** Saying "I'll take this" reserves nothing. Open a pull request, or say in the issue that you have started, and expect that someone else may get there first.
- **Third-party bounties are not recognised.** Money attached to an issue by someone outside the project does not put it on the roadmap and creates no obligation to merge. Pull requests are judged on their merits, exactly as they would be without it.
- **Keep payment arrangements off the tracker.** Agree terms with whoever pays you elsewhere; comments about budgets, invoices, payment timing or wallet addresses are off-topic here and will be hidden as such.
- **Propose a large or unsolicited feature as an issue first.** A substantial pull request for something nobody discussed is likely to be declined on scope no matter how well it is written — a short design issue costs you an hour instead of a week.
- **Disclose AI-assisted work, and expect it reviewed as code of unverified provenance.** The DCO still applies: you certify that you have the right to submit it. Claims in the description must be measured against the real client or protocol rather than inferred from a similar one, and a `COMPAT.md` entry has to match what the code actually does.

## Project Governance

NORA uses a **Benevolent Dictator** governance model:

- **Maintainer:** [@devitway](https://github.com/devitway) — final decisions on features, releases, and architecture
- **Contributors:** anyone who submits issues, PRs, or docs improvements
- **Decision process:** proposals via GitHub Issues → discussion → maintainer decision
- **Release authority:** maintainer only

### Roles and Responsibilities

| Role | Person | Responsibilities |
|------|--------|-----------------|
| Maintainer | @devitway | Code review, releases, roadmap, security response |
| Contributor | anyone | Issues, PRs, documentation, testing |
| Dependabot | automated | Dependency updates |

### Continuity

The GitHub organization [getnora-io](https://github.com/getnora-io) has multiple admin accounts to ensure project continuity. Source code is MIT-licensed, enabling anyone to fork and continue the project.

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/nora.git`
3. Create a branch: `git checkout -b feature/your-feature`

## Development Setup

### Prerequisites

- **Rust** stable (1.85+) — install via [rustup](https://rustup.rs/)
- **Docker** (optional) — for integration tests (docker push/pull)
- **Node.js** 18+ (optional) — for npm integration tests

### Build and Test

```bash
# Build
cargo build --package nora-registry

# Run unit tests (important: use --lib --bin to skip fuzz targets)
cargo test --lib --bin nora

# Run clippy (must pass with zero warnings)
cargo clippy --package nora-registry -- -D warnings

# Format check
cargo fmt --check
```

### Run Locally

```bash
# Start with defaults (port 4000, local storage in ./data/)
cargo run --bin nora -- serve

# Custom port and storage
NORA_PORT=5000 NORA_STORAGE_PATH=/tmp/nora-data cargo run --bin nora -- serve

# Test health
curl http://localhost:4000/health
```

### Integration / Smoke Tests

```bash
# Build release binary first
cargo build --release

# Run full smoke suite (starts NORA, tests all 15 protocols, stops)
bash tests/smoke.sh
```

### Fuzz Testing

```bash
# Install cargo-fuzz (one-time)
cargo install cargo-fuzz

# Run fuzz target (Ctrl+C to stop)
cargo +nightly fuzz run fuzz_validation -- -max_total_time=60
```

## Changelog entries

Do not edit `## [Unreleased]` in `CHANGELOG.md` directly. Add a fragment instead:

```bash
cat > changelog.d/<issue-or-pr-number>.<category>.md <<'EOF'
**Short title (#N)** — what changed, what it was before, and why it matters.
EOF
```

`<category>` is one of `added`, `changed`, `deprecated`, `removed`, `fixed`,
`security`. One file per change means two pull requests never edit the same lines, so
they cannot conflict on the changelog — which they did three times in a row during
1.3.1. `scripts/changelog-fragments.sh --check` validates the fragments and
`--render` shows the assembled section; the maintainer runs `--release <version>` at
release time. See `changelog.d/README.md`.

## Before Submitting a PR

```bash
cargo fmt --check
cargo clippy --package nora-registry -- -D warnings
cargo test --lib --bin nora
```

All three must pass. CI will enforce this.

**Sign your commits.** `main` requires **verified GPG-signed commits** — an unsigned commit cannot be merged and a maintainer has to re-sign (reland) it by hand, which delays your PR. Configure signing once:

```bash
git config commit.gpgsign true   # or per-commit: git commit -S
```

See [GitHub's guide to signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). The commit email must match a verified key on your GitHub account, or the commit shows as *Unverified*.

## Code Style

- Run `cargo fmt` before committing
- Fix all `cargo clippy` warnings
- No `unwrap()` in production code (use proper error handling)
- Follow Rust naming conventions
- Keep functions short and focused
- Add tests for new functionality
- Environment variable names follow `NORA_{SECTION}_{FIELD}` pattern. Use short abbreviations for long compound words (e.g. `NORA_CB_*` instead of `NORA_CIRCUIT_BREAKER_*`). Aim for under 30 characters total.

## Pull Request Process

1. Branch from `main`, use descriptive branch names (`feat/`, `fix/`, `chore/`)
2. Update CHANGELOG.md if the change is user-facing
3. Add tests for new features or bug fixes
4. Ensure CI passes (fmt, clippy, test, security checks)
5. Keep PRs focused — one feature or fix per PR
6. PRs are squash-merged to keep a clean history

## Commit Messages

Use conventional commits:

- `feat:` new feature
- `fix:` bug fix
- `docs:` documentation
- `test:` adding or updating tests
- `security:` security improvements
- `chore:` maintenance

Example: `feat: add npm scoped package support`

## New Registry Checklist

When adding a new registry type (Docker, npm, Maven, etc.), ensure all of the following:

- [ ] Handler in `nora-registry/src/registry/`
- [ ] Health check endpoint
- [ ] Metrics (Prometheus)
- [ ] OpenAPI spec update
- [ ] Startup log line
- [ ] Dashboard UI tile
- [ ] Playwright e2e test
- [ ] CHANGELOG entry
- [ ] COMPAT.md update

## Reporting Issues

- Use GitHub Issues with the provided templates
- Include steps to reproduce
- Include NORA version (`nora --version`) and OS

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

## Community

- Telegram: [@getnora](https://t.me/getnora)
- GitHub Issues: [getnora-io/nora](https://github.com/getnora-io/nora/issues)