# Contributing to stac-client-rs
Thank you for your interest in contributing! This document provides guidelines for contributors and maintainers.
## Development Guidelines
Please review **`AGENTS.md`** for detailed policies and best practices, including:
- Rust best practices and code style
- Testing and coverage requirements
- Dependency evaluation criteria
- PR checklist requirements
- Architecture governance (ADR/ASR)
## Quick Start for Contributors
1. Fork the repository
2. Create a feature branch following the naming conventions below
3. Make your changes following the coding standards
4. Run tests and linting: `cargo test && cargo fmt -- --check && cargo clippy -- -D warnings`
5. Submit a pull request
## Branch Naming Conventions
We support two methods for determining version bumps on merged PRs:
### Label-Based Versioning (Recommended)
Apply one of these labels to your PR to specify the version bump:
- `bump:hotfix` - Bug fixes and patches (0.1.0 → 0.1.1)
- `bump:minor` - New features, backwards compatible (0.1.0 → 0.2.0)
- `bump:release` - Breaking changes (0.1.0 → 1.0.0)
**Labels take priority over branch names** if both are present.
### Branch-Based Versioning (Legacy)
Branch prefixes can also determine the type of release:
- `feature/*` - New features (triggers minor version bump)
- `fix/*` or `hotfix/*` - Bug fixes (triggers patch version bump)
- `release/*` - Major releases (triggers major version bump)
## Release Process
### Automatic Releases (PR-based)
When a PR is merged to `main`, the release workflow automatically determines the version bump based on PR labels (if present) or branch name and publishes to crates.io.
**Using Labels**: Add one of `bump:hotfix`, `bump:minor`, or `bump:release` labels to your PR before merging.
**Using Branches**: If no label is present, the workflow will use the branch naming conventions described above.
#### Setting Up Labels
To create the semantic versioning labels in your repository, use the GitHub CLI:
```bash
gh label create "bump:hotfix" --description "Patch version bump (0.1.0 → 0.1.1)" --color "d73a4a"
gh label create "bump:minor" --description "Minor version bump (0.1.0 → 0.2.0)" --color "0075ca"
gh label create "bump:release" --description "Major version bump (0.1.0 → 1.0.0)" --color "a2eeef"
```
Or reference the `.github/labels.yml` file for label configuration.
### Manual Releases (Maintainers Only)
Repository administrators and owners can manually trigger a release:
1. Go to the **Actions** tab in GitHub
2. Select **Manual Release** workflow
3. Click **Run workflow**
4. Choose the version bump type:
- `patch` - Bug fixes and minor changes (0.1.0 → 0.1.1)
- `minor` - New features, backwards compatible (0.1.0 → 0.2.0)
- `major` - Breaking changes (0.1.0 → 1.0.0)
5. Click **Run workflow** to start the release
The workflow will:
- Bump the version in `Cargo.toml`
- Build and test the code
- Publish to crates.io
- Create a git tag
- Create a GitHub release with auto-generated release notes
**Note**: Ensure you have configured the required secrets:
- `CARGO_REGISTRY_TOKEN` - Token for publishing to crates.io
- `GH_PAT` (optional) - Personal access token for enhanced GitHub operations
## Testing
All changes must include appropriate tests:
```bash
# Run all tests
cargo test
# Run tests with coverage
./scripts/coverage.sh
```
Current coverage requirement: 80% (temporary, targeting 100%)
## Code Quality
Before submitting a PR:
```bash
# Format code
cargo fmt
# Check formatting
cargo fmt -- --check
# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
```
## Pull Request Checklist
- [ ] Code formatted: `cargo fmt`
- [ ] Linted: `cargo clippy` (no warnings)
- [ ] Tests included and passing: `cargo test`
- [ ] Coverage meets requirements (80%+)
- [ ] Version bumped if releasing (with tag and changelog entry)
- [ ] Dependency rationale included (if applicable)
- [ ] ADR/ASR review performed (if architecturally significant)
## Questions?
If you have questions or need help, please open an issue or discussion in the repository.