nora/CONTRIBUTING.md

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. Your contribution will be licensed under the MIT License.

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

Project Governance

NORA uses a Benevolent Dictator governance model:

• Maintainer: @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 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
• Docker (optional) — for integration tests (docker push/pull)
• Node.js 18+ (optional) — for npm integration tests

Build and Test

# 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

# 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

# Build release binary first
cargo build --release

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

Fuzz Testing

# 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

Before Submitting a PR

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

All three must pass. CI will enforce this.

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

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
• GitHub Issues: getnora-io/nora