mirror of
https://github.com/getnora-io/nora.git
synced 2026-04-12 10:20:32 +00:00
DevITWay | Pavel Volkov
7d8116034a
Add prerequisites, local run instructions, smoke test guide, and fuzz testing section. Helps new contributors get started.
148 lines
3.9 KiB
Markdown
148 lines
3.9 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
|
|
- Follow Rust naming conventions
|
|
- Keep functions short and focused
|
|
- Add tests for new functionality
|
|
|
|
## Pull Request Process
|
|
|
|
1. Update CHANGELOG.md if the change is user-facing
|
|
2. Add tests for new features or bug fixes
|
|
3. Ensure CI passes (fmt, clippy, test, security checks)
|
|
4. Keep PRs focused — one feature or fix per PR
|
|
|
|
## 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`
|
|
|
|
## 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)
|