index.md

Introduction

Creating a new Rust project is as easy as typing cargo new <project_name> but often, you need more than what cargo new gives you.

This is when cargo generate comes into play:

cargo-generate is a developer tool to help you get up and running quickly with a new Rust project by leveraging a pre-existing git repository as a template.

Rust GitHub Template (this project) is a template for cargo generate that aims to be a starting point suitable for rust projects hosted on GitHub.

Stop copy-pasting tons of markdown and yaml files each time you start a new rust project. Let's write them only once, together!

You can see an example project generated with this template here.

Template content

GitHub Actions

• security checks
• continuous integration - on pull request or push:
  • tests
  • rustfmt
  • clippy
  • docs
  • publish-dry-run
• continuous delivery - on every git tag in the [v]?[0-9]+.[0-9]+.[0-9]+ format (for example v0.2.14):
  • publish release for mac, linux and windows
  • publish to cargo

Documentation

• Installation instructions
• README badges
  • crates.io
  • docs.rs
  • GitHub Actions CI
• Licenses (MIT or APACHE)
• Changelog
• Contributing guidelines
• Code of conduct
• Issue templates (see result)
• Pull request template

Instructions

Project creation

• Install cargo generate (version >= 11.0).

  cargo install cargo-generate --locked

• Create your project with this template.

  cargo generate --git https://github.com/rust-github/template.git

• cd into your project.

• Edit your project according to your own needs by adding what's necessary and removing what you don't like.

• Create a new empty repository (do not initialize it with a README, a .gitignore or a license).

• Follow GitHub instructions to "push an existing repository from the command line".

Crates.io

Set up your crates.io token in a GitHub secret called CARGO_REGISTRY_TOKEN.

For more info about the crates.io tokens, see The Cargo Book.

Publish

If this is your first ever crate, ensure your email address is verified on crates.io before you publish.

When you are ready to publish the first version of your application, run:

git tag -a 0.1.0
git push --follow-tags

This tag should trigger the continuous deployment, that will:

• Publish your application on crates.io
• Publish the binaries on GitHub Releases

Supporting Rust Github Template

The best way to support the project is to contribute to it by reporting problems, ideas or sending pull requests.

If you created your project by using Rust GitHub Template, and you want to show it, you can use our badge:

• For Markdown:

  [![Rust GitHub Template](https://img.shields.io/badge/Rust%20GitHub-Template-blue)](https://rust-github.github.io/)

• For HTML:

  <a href="https://rust-github.github.io/"><img alt="Rust GitHub Template" src="https://img.shields.io/badge/Rust%20GitHub-Template-blue" /></a>

Thank you! 🙏

Links

• choices explanation
• credits