rust_lib_example 0.2.0

Rust project example
Documentation

Example of Rust project

Crates.io Docs.rs License CI Coverage with grcov Mutation tested with mutagen Lines of code

Purpose

This repository contains an example of Rust project structure.

Most of the components can be reusable in your own projects:

  • Project configuration
  • CI workflow to build, lint, test, check test coverage and run mutation tests
  • CD workflow to test on all platforms and publish on crates.io

Github Actions workflows

Jobs

The CI workflow is triggered for any commit or pull request on the main branch and runs the following jobs:

  • Test the crate
    • Build the project for all targets and with default features to ensure everything compiles
    • Run unit, integration and doc tests with default features
  • Run test coverage and mutation tests
    • Run source-based coverage with grcov
    • Upload HTML coverage report in workflow artifacts
    • Upload HTML coverage report on Codecov
    • Fail if the coverage threshold is not reached
    • Run mutation tests with mutagen (note that the job automatically adds #[mutate] annotations)
    • Fail if the mutation threshold is not reached
  • Run several code checks
    • Run clippy
    • Run rustfmt to check code is correctly formatted
    • Run cargo-deny to check dependencies
    • Check encoding of all files is UTF-8
    • Check all line endings are LF
    • Check there is no TODO left in Rust code

This workflow is only run on Ubuntu virtual environment.

The CD workflow is triggered manually and runs the following jobs:

  • Check version to release in Cargo.toml files
  • Test on Ubuntu
  • Test on Windows
  • Test on MacOS
  • Make a publication dry run on crates.io
  • Publish on crates.io
  • Create the release and prepare the next one in the repository
    • Update the latest version and its release date in the CHANGELOG.md file and push the changes
    • Tag the created commit with the name of the released version
    • Create a GitHub release from the created tag and the content of the CHANGELOG.md file
    • Create a new section for the next release in the CHANGELOG.md file and push the changes

Secrets

The CD workflow requires the following secrets:

  • CRATES_IO_TOKEN: token to publish the crate(s) on crates.io
  • GIT_TOKEN: GitHub personal access token to allow pushing changes as administrator (if the main branch is protected, "Include administrators" must be unchecked in settings)

These secrets must be stored in a repository environment called Deployment.

Settings

Settings of the CI workflow can be modified in the file .github/workflows/ci.yml, in the env section:

  • RUST_VERSION_STABLE: version of the stable Rust compiler to use
  • RUST_VERSION_NIGHTLY: version of the nightly Rust compiler to use when required
  • MUTAGEN_COMMIT: commit of the mutagen version to install (from mutagen repository)
  • COV_THRESHOLD: minimum threshold the coverage must reached to succeed the job
  • MUTAGEN_THRESHOLD: minimum threshold the mutation tests must reached to succeed the job
  • CRATE_PATHS: package names separated by ; in publication order if the repository is a Cargo workspace, else .

Settings of the CD workflow can be modified in the file .github/workflows/cd.yml, in the env section:

  • RUST_VERSION_STABLE: version of the stable Rust compiler to use
  • CRATE_PATHS: package names separated by ; in publication order if the repository is a Cargo workspace, else .

Run locally

act can be used to run the workflows on your own machine. Once installed, run act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04 in the repository folder to run all supported jobs.

Workspaces

This repository contains a single crate, but the workflows should also work with a Cargo workspace.

Adaptations for another project

This project example is made to be reused. If you are interested in using this template, you can copy the files in your own project and:

  • adapt the settings of the CI workflow in the file .github/workflows/ci.yml, in the env section
  • adapt the settings of the CD workflow in the file .github/workflows/cd.yml, in the env section
  • edit the .lints, deny.toml, rustfmt.toml, Cargo.toml and README.md files as wanted
  • edit the issue templates in .github/ISSUE_TEMPLATE as wanted
  • reset the CHANGELOG.md file (make sure there is at least a section ## [Unreleased] - yyyy-mm-dd)
  • change the copyright notices in the LICENSE-MIT and LICENSE-APACHE files if you keep these licenses
  • in the repository settings, create a GitHub environment named Deployment with the CRATES_IO_TOKEN and GIT_TOKEN secrets
  • if the main branch is configured as protected, make sure Include administrators is unchecked in the configuration

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.