# Contributing to opencode-ralph-loop-cli
> This document is also available in [Português](CONTRIBUTING.pt-BR.md).
> Every contribution — bug reports, documentation fixes, new features — makes this project better for everyone.
## Quick Start
### Setup — Get Running in Five Commands
- Clone the repository and enter the directory
- Run `cargo build` to compile the project
- Run `cargo nextest run` to execute all tests
- Run `cargo clippy -- -D warnings` to check for lint errors
- Run `cargo fmt --check` to verify formatting
```bash
git clone https://github.com/daniloaguiarbr/opencode-ralph-loop-cli
cd opencode-ralph-loop-cli
cargo build
cargo nextest run
```
## Code of Conduct
### Standards — Community Expectations
- Read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing
- All interactions must meet the standards described in that document
- Violations are reported to: claude.ai.twenty614@passmail.net
## Development Setup
### Requirements — Tools You Need
- Rust 1.85 or later (MSRV) — install via rustup
- `bun` or `node` — for testing opencode integration
- `cargo-nextest` — `cargo install cargo-nextest`
- `cargo-llvm-cov` — `cargo install cargo-llvm-cov`
- `cargo-audit` — `cargo install cargo-audit`
- `cargo-deny` — `cargo install cargo-deny`
## Branching Strategy
### Workflow — Branch Naming Convention
- `main` is the stable production branch — do not push directly
- `feature/<description>` for new functionality
- `fix/<description>` for bug fixes
- `docs/<description>` for documentation changes
- Open a pull request from your branch to `main`
## Commit Convention
### Format — Conventional Commits Standard
- Use prefix `feat:` for new user-visible features
- Use prefix `fix:` for bug corrections
- Use prefix `perf:` for performance improvements
- Use prefix `refactor:` for code restructuring without behavior change
- Use prefix `docs:` for documentation updates
- Use prefix `chore:` for maintenance tasks (CI, deps, tooling)
- Breaking changes: append `!` after prefix (e.g., `feat!:`)
- Example: `feat: add --keep-state flag to uninstall command`
## Pull Request Process
### Checklist — Eight Required Gates
- `cargo check --all-targets` passes with zero errors
- `cargo clippy --all-targets --all-features -- -D warnings` passes with zero warnings
- `cargo fmt --all --check` passes with zero differences
- `cargo doc --no-deps --all-features` passes with zero warnings
- `cargo nextest run` passes all tests
- `cargo llvm-cov --text` reports at least 80 percent coverage
- `cargo audit` reports zero vulnerabilities
- `cargo deny check advisories licenses bans sources` passes
## Testing
### Practice — How We Test This Project
- Unit tests live inline in each module under `#[cfg(test)]`
- Integration tests live in `tests/` using `assert_cmd`
- Property-based tests in `tests/proptest_tests.rs` using `proptest`
- Run `cargo nextest run` for the full test suite
- Run `cargo llvm-cov --text` to measure coverage (minimum 80 percent)
## Documentation
### Updates — Keep Docs in Sync
- Update `README.md` when adding or changing commands or flags
- Update `CHANGELOG.md` under `[Unreleased]` for every user-facing change
- Run `cargo doc --no-deps` to verify doc comments compile
## Reporting Bugs
### Template — What to Include
- Describe the command you ran (exact invocation)
- Describe what you expected to happen
- Describe what actually happened (include exit code)
- Include your OS, Rust version, and crate version
- Open an issue at https://github.com/daniloaguiarbr/opencode-ralph-loop-cli/issues
## Requesting Features
### Template — How to Propose
- Describe the problem you are trying to solve first
- Explain why existing commands do not solve it
- Propose the new subcommand or flag with expected behavior
- Open an issue at https://github.com/daniloaguiarbr/opencode-ralph-loop-cli/issues
## Release Process
### Authorization — Maintainer Only
- Only project maintainers may publish new releases to crates.io
- Releases follow Semantic Versioning 2.0.0 strictly
- Each release requires all ten validation commands to pass
- Tags follow the pattern `vX.Y.Z` exactly