rust-template

A github rust workflows template, just want to focus on coding.

• Who uses?
• Demo template
• GitHub Actions
• Workflow file

Table of contents

• Features
• Usage
• Template options
• Template workflows
• Contributors
• License

Features

• Directly create your Github repository
• Fast generate template with GitHub Actions
• Support cargo-generate

Template

• Based on conventional commits
• Based on push vTag
• Bumps Crate version
• Create GitHub tag
• Generate Changelog
• Continuous integration with caching
• Cross-platform static compilation
• Upload artifact
• Publish to Crates
• Publish to Docker hub
• Publish to Github releases
• contrib.rocks
• starcharts

Usage

Use GitHub actions

This will not affect your Github, give it a try:

1. Use this template.
2. Under your repository name, click Actions.
3. In the left sidebar, click the Generate.
4. Above the list of workflow runs, click the Run workflow button.
5. When all work is done, at the bottom of the workflow summary page, download template artifacts.
6. Enjoy!

If need directly create your Github repository, in addition to all the above steps, you also need:

1. Creating a fine-grained personal access token.

   Repository access: All repositories

   Permissions > Repository permissions: Administration Contents Workflows > Access: Read and write

2. Copy personal access token.

3. Creating encrypted secrets for a repository.

   Name field: PAT_ADMIN_CODE_WORKFLOWS

Use cargo-generate

See more.

# bin
cargo generate --git https://github.com/uplau/rust-template ./template --name "crate-name" --bin

# lib
cargo generate --git https://github.com/uplau/rust-template ./template --name "crate-name" --lib

Template options

Field	Type	Default	Description
crate-name	string	required	Package name
crate-type	bin or lib	bin	Linkage
owner	string	required	Owner, for filling README and LICENSE and note Cargo.toml
copyright-year	string	2023	Copyright year, for filling LICENSE
use-badge	bool	true	Insert status badge to README top
use-contrib-rocks	bool	false	Insert contrib.rocks to README#Contributors
use-deps	bool	true	Insert commonly use deps to Cargo.toml
use-rust-template	bool	true	Insert rust-template to README#Contributing

Template workflows

Workflows of bin can be view:

• workflow file
• on push and pull request summary
• release please PR
• automatic release summary
• automatic release assets
• manually release summary
• manually release assets

Workflows of lib can be view:

• workflow file
• manually summary

jobs.release_please

We use Release Please parses your git history, looking for conventional commits, and creating release PRs to:

What's a Release PR?

How should I write my commits?

Does not create a release PR. Why?

You need allow GitHub Actions to create and approve pull requests, setting can be managed by admins in organization settings under Actions > General > Workflow permissions.

• Bumps Crate version
• Create Github tag
• Generate Changelog

jobs.ci

We run the following command to complete continuous integration:

rust-template/template/.github/workflows/cicd.yaml

Line 53 in 7b8fe91

os: [macos-latest, ubuntu-latest, windows-latest]

• cargo test
• cargo fmt
• cargo clippy

jobs.build only_bin

When the ci passed, we build statically linked binaries under the following targets and upload the artifacts:

You can modify it as you like, but you need to pay attention to some extra steps for some target.

rust-template/template/.github/workflows/cicd.yaml

Lines 89 to 103 in 7b8fe91

	- target: aarch64-apple-darwin
	os: macos-latest
	- target: aarch64-unknown-linux-musl
	os: ubuntu-latest
	use-cross: true
	- target: x86_64-apple-darwin
	os: macos-latest
	- target: x86_64-unknown-linux-musl
	os: ubuntu-latest
	- target: x86_64-pc-windows-msvc
	os: windows-latest

jobs.*_release only_bin

When the build passed, we download the artifacts and publish to Github releases, which you can download at any time at the bottom of the workflow summary page:

• manually_release: Triggered by workflow_dispatch
• automatic_release: Triggered by release_please

Contributors

License

rust-template is licensed under either of the following, at your option:

• MIT License
• Apache-2.0 License