Contributing to Crater.rs
Commit Message Guidelines
Crater.rs uses git-cliff
to generate changelogs based on commit messages. Please follow the syntax defined in ./cliff.toml
.
Examples
For new features:
feat: new feature added
For bug fixes:
fix: bug squashed!
Development Setup
Building the Documentation
To build and serve the mdBook locally with hot-reload:
./scripts/build-docs.sh --serve
This will start a local server at http://localhost:3000 with automatic reload when you make changes to the documentation.
Running Tests
Before submitting changes, ensure all tests pass:
cargo test
Static Analysis and Styling
Before submitting changes, ensure the project passes lint checks:
./scripts/static-analysis.sh
Release Process (Maintainers Only)
Crater.rs uses cargo-release
for automated releases. The release process is handled by CI/CD:
How Releases Work
- Automated CI/CD Pipeline: The
release
job in CI configures git for direct push access via OAuth - cargo-release Execution: This tool automatically:
- Runs
./scripts/pre-release.sh
which:- Executes end-to-end tests and generates artifacts in
./artifacts
- Runs
git-cliff
(configured incliff.toml
) to generate changelog
- Executes end-to-end tests and generates artifacts in
- Updates version numbers across all relevant files
- Publishes to crates.io
- Creates commit with changes tagged as "chore" (skips CI to avoid loops)
- Adds git tag for the release
- Pushes changes and tags to the main branch
- Runs
Creating a Release
As a maintainer, when a merge request lands:
- The
release
job becomes available for manual execution - Start the job with the appropriate bump level:
BUMP_LEVEL=(patch|minor|major)
Choose the bump level based on the type of changes:
- patch: Bug fixes and small improvements
- minor: New features that maintain backward compatibility
- major: Breaking changes
The automated process handles everything else, ensuring consistent and reliable releases.