mirror of
https://github.com/getnora-io/nora.git
synced 2026-04-12 05:40:31 +00:00
DevITWay | Pavel Volkov
b3239ed2d7
* chore: add workspace clippy lints, release profiles, COMPAT.md, diff-registry.sh - Workspace clippy lints: or_fun_call, redundant_clone, collection_is_never_read, naive_bytecount, stable_sort_primitive, large_types_passed_by_value, assigning_clones - Fix or_fun_call in cargo_registry.rs (unwrap_or -> unwrap_or_else) - Release profiles: release (thin LTO) + release-official (full LTO, codegen-units=1) - COMPAT.md: protocol compatibility matrix for all 7 registries (40 endpoints) - scripts/diff-registry.sh: differential smoke tests (Docker/npm/Cargo/PyPI/Go/Raw) * ci: add typos spell-check job and config * chore: add .git-blame-ignore-revs for bulk fmt/clippy commits * chore: unify PR template with What/Why/Checklist format * docs: add new registry checklist and improve contributing guide * fix: correct typos action SHA to v1.45.0
165 lines
4.4 KiB
Markdown
165 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
## 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 7 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
|
|
```
|
|
|
|
## 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.
|
|
|
|
## 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](https://t.me/getnora)
|
|
- GitHub Issues: [getnora-io/nora](https://github.com/getnora-io/nora/issues)
|