Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (76 loc) · 3.57 KB

CONTRIBUTING.md

File metadata and controls

91 lines (76 loc) · 3.57 KB
Raw

Contributing

All types of contributions are encouraged and valued.

Build Instructions

Install Rust with Rustup using Rustup.

Fork, then clone the repo:

$ git clone {github repo}

Make your change. Add tests for your change. Make the tests pass:

$ cargo test

For cargo coverage, run the following commands:

$ rustup default stable
$ rustup component add llvm-tools
$ export PATH=`rustc --print=sysroot`/lib/rustlib/x86_64-unknown-linux-gnu/bin/:${PATH}

Push to your fork and submit a pull request.

Expectations

For each PR branch, ensure that the source code

  1. is formatted with cargo fmt
  2. has no warnings from clippy
  3. has properly formatted documentation
  4. can build against MUSL for x86 and arm architectures

Releases

The release process strives to ensure that each release contains the following:

  1. A succinctly-worded release body
  2. A git tag with a matching version
  3. A copy of the pre-compiled idlc that was generated by the Github CI

The release process involves some automation and the following steps should be carefully followed to ensure uniformity among the releases.

Due to the structure of this repo and QUIC policies, some obvious approaches to automating releases are not possible. The current approach uses a mix of semi-manual updates with cargo-workspaces and automated releases with release-please.

Release-prep model

Changes are introduces through Pull Requests (PRs) that are merged through squash commits.

When making changes, be sure to use Conventional Commits. That is, prefix your commit messages with feat:, fix:, deps:, etc. Since we use squash commits for PRs, the tip of your PR branch must contain the prefix keyword.

Version Policy

  • PRs:
    • modify code only
    • never touch versions
  • Versions are bumped only during release preparation
  • cargo ws changed determines affected crates
  • Patch/minor/major is chosen intentionally
  • Version bumps are committed as a single release commit

Release Procedure

  • A release PR will be created and updated by release-please
    • CHANGELOG.md and release message body automatically updated, based on
    • Updates the release-please manifest
  • After 1 or more version bumps, a release PR can be merged
  • release-please rebuilds the target binaries and uploads them to the release itself.

Benefits

  1. Squash merges freely
  2. main stays clean and stable
  3. No version churn, no Cargo.lock noise

Example

Here is an example of the typical development flow:

  1. Merge 1 or more feature/patch/bug fix PRs (no version changes)
  2. Prepare for release 
    1.  cargo install cargo-workspaces
 cargo ws changed
 cargo ws version --no-git-push --no-git-tag -m "chore(release): bump crate versions"
      1. This analyzes the workspace, bumps the Cargo.toml (AND Cargo.lock) versions based solely on if any changes occur within the crate, and commits the changes.
      2. cargo ws will prompt for each crate to specify which type of release (major, minor, or patch) is appropriate.
      3. The release type is determined by the user
    2. Review the commit
    3. Push to origin/main - either directly or through PR.
  3. release-please captures all conventional commits through PRs and "bump" commit
  4. Review release-please release PR to make sure everything is captured correctly
  5. Merge release PR and release-please takes care of the rest