rust-ci

Rust CI

A template for generating Rust projects that make use of some common continuous-integration services

Sets up a Rust crate to make use of some freely-available testing tools, with the option of adding extra automation if so desired. Features:

• Travis CI/AppVeyor: Automated crate testing on Linux, MacOS and Windows
• rustfmt: Builds fail if code is out of style
• Codecov: (Optional) Code coverage statistics for test cases
• Bors NG: (Optional) “Strict mode” pull request management
• crates.io: (Optional) Automatically publish to crates.io by pushing a git tag
• cross: (Optional) Test on more than just x86/_64 architectures

Setup

It’s easy to start new projects, and migrate existing projects to the new infrastructure. But if you already have a CI workflow you like - keep it.

New Projects

To set up your own crate making use of this template, do the following:

pip install --user cookiecutter
cookiecutter gh:bspeice/rust-ci

A series of prompts will walk you through the remaining options:

full_name

Used in locations like Cargo.toml to identify the author

email

Used in locations like Cargo.toml to identify the author

github_username

The username Github refers to you by; needed for links throughout the template

crate_name

The name of the crate you are authoring. This is assumed to be the same name as the Git repository.

project_type

Whether to generate a library or binary project, similar to cargo init --lib and cargo init --bin.

use_bors

Yes/no whether to use the Bors bot for automating merging of pull requests. For instructions on using Bors, please see https://bors.tech/documentation/getting-started/#reviewing-pull-requests

use_codecov

Yes/no whether to record code coverage statistics at Codecov.

use_cargo_cross

By default, Travis/Appveyor can only build on x86/_64 hosts for Linux, Mac OSX, and Windows. If this option is selected, the rust-embedded/cross will be used for testing on a much wider range of architectures.

license

Options for the default LICENSE file

cratesio_api_token

Token for publishing to crates.io using an automated build. Tokens are encrypted before commit so there are no worries about publishing sensitive information.

If you choose not to publish to crates.io in an automated fashion, please leave this field blank.

When the token is specified, a new version of the crate can be published to crates.io by pushing a git tag of the format vX.Y.Z where X, Y, and Z are the major, minor, and patch numbers respectively.

Two important things to keep in mind:

1. There are no checks for the git tag and Cargo.toml containing the same version number
2. [Workspace](https://doc.rust-lang.org/cargo/reference/manifest.html#the-workspace-section) and multi-crate setups
will need more hands-on work than this template can provide. Please see
[Travis' custom deployment](https://docs.travis-ci.com/user/deployment/custom/)
page to learn more about automated deploys for these scenarios.

Migrating existing projects

This template is designed to make migrations from trust and projects without CI very easy. Workspace projects are difficult to migrate, but individual crates should be simple.

To migrate:

1. Initialize a new project folder as outlined above. When prompted for the project_type, please use the same type as the code being migrated.
2. rm new_project/.git -r and cp old_project/.git new_project/.git -r to make sure no history is lost
3. Copy your original project files over; this includes things like:
   • src
   • testing
   • examples
   • Cargo.toml
   • etc.
4. Add the new files in Git and commit to preserve the changes - git add . && git commit

Usage

Most of the services run automatically. That said, there are some important notes for where humans are still needed to maintain the project:

• If using bors, please take note of their documentation to understand the desired workflow
• If you added a crates.io API key, all that is needed to publish a new release is pushing a git tag. Travis will automatically build and deploy tags of the form vX.Y.Z.
• There is a Makefile included to help with generation of the README.md and CONTRIBUTORS.md files. Please run make doc prior to release to update this documentation