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

  1. Automated CI/CD Pipeline: The release job in CI configures git for direct push access via OAuth
  2. 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 in cliff.toml) to generate changelog
    • 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

Creating a Release

As a maintainer, when a merge request lands:

  1. The release job becomes available for manual execution
  2. 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.