Skip to content

GETTING-STARTED.md

Latest commit

 

History

History
236 lines (170 loc) · 9.17 KB

GETTING-STARTED.md

File metadata and controls

236 lines (170 loc) · 9.17 KB
Raw
diataxis_type how-to

Getting Started

You just created a repository from zircote/rust-template. This guide walks you through every step from creation to your first green CI run.

1. Create Your Repository

  • Go to zircote/rust-template and click "Use this template" > "Create a new repository".
  • Choose an owner (your user or an organization).
  • Name your repository (e.g., my-awesome-crate).
  • Select Public or Private visibility.
  • Click "Create repository".

Optional: During creation, GitHub offers a "Jumpstart your project with Copilot" field. You can paste a prompt there to have Copilot scaffold your project with real types, functions, and tests in an auto-opened PR. See Copilot Jumpstart for ready-made prompts.

2. Automatic Initialization

Once your repository is created and the first push lands on main, the Template Init workflow (template-init.yml) runs automatically. It performs the following replacements across the entire repository:

Template placeholder Replaced with Example
zircote/rust-template your-org/your-repo acme/my-awesome-crate
zircote your GitHub owner acme
rust-template your repository name my-awesome-crate
rust_template your crate name (underscored) my_awesome_crate

What to expect:

  • The workflow takes roughly 1 minute to complete.
  • It creates a commit titled chore: initialize from rust-template for <owner>/<repo>.
  • After the commit, Cargo.toml, README.md, documentation links, and all other references point to your project.
  • The workflow becomes a no-op on subsequent pushes (it checks whether Cargo.toml still contains rust_template).

What copies and what doesn't? Files copy; settings don't. See GitHub Template Features for the full breakdown of what transfers when you use a template repository.

3. Clone and Build

After the init workflow completes, pull down your freshly initialized repo:

git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>

Build and run the test suite:

cargo build
cargo test

Requirements

Requirement Minimum version
Rust toolchain 1.92 or newer
Rust edition 2024
cargo-deny (optional, for supply chain checks) latest stable

Install the Rust toolchain using the official rustup installer:

# Install rustup (do NOT use Homebrew — `brew install rust` installs an
# unmanaged toolchain that cannot switch versions, add targets, or run
# `rustup` commands used throughout this project)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the on-screen prompts, then reload your shell:
source "$HOME/.cargo/env"

# Set the default toolchain and verify
rustup default stable
rustup update
rustc --version   # should print 1.92.0 or newer

Already have Homebrew's rust or rust-analyzer formula? Remove it first to avoid conflicts:

brew uninstall rust rust-analyzer 2>/dev/null

rustup manages both rustc and rust-analyzer automatically. Homebrew and rustup cannot coexist for the same binaries without $PATH conflicts.

4. Explore the Structure

.
├── crates/
│   ├── lib.rs              # Library entry point and public API
│   └── main.rs             # Binary entry point (optional)
├── tests/
│   └── integration_test.rs # Integration tests
├── benches/                # Benchmarks (criterion)
├── examples/               # Example programs
├── docs/                   # Documentation
├── .github/
│   └── workflows/          # CI/CD pipelines
├── Cargo.toml              # Package manifest
├── deny.toml               # cargo-deny configuration
├── rustfmt.toml            # Formatting rules
└── clippy.toml             # Linting rules

Key points:

  • Source code lives under crates/, not src/. The paths are configured in Cargo.toml via [lib] and [[bin]].
  • Unit tests go inside crates/*.rs files within #[cfg(test)] modules.
  • Integration tests go in the tests/ directory.
  • CI/CD workflows are in .github/workflows/. The template ships with 30+ workflows covering CI, security, releases, and more.

5. First CI Pass

Push any change (or wait for the init commit) and verify CI passes:

git add -A
git commit -m "feat: initial implementation"
git push

Open the Actions tab in your GitHub repository to watch the pipeline. The core CI workflow runs these checks:

Check What it does Command
Format Enforces consistent code style cargo fmt --all -- --check
Clippy Lints with pedantic + nursery rules cargo clippy --all-targets --all-features -- -D warnings
Test Runs tests on Linux, macOS, and Windows cargo test --all-features --verbose
Documentation Verifies rustdoc builds cleanly cargo doc --no-deps --all-features
Cargo Deny Audits licenses, advisories, and sources cargo deny check
MSRV Confirms the crate builds on Rust 1.92 cargo check --all-features
Coverage Generates code coverage via cargo-llvm-cov cargo llvm-cov --all-features

All checks (except coverage) must pass for the "All Checks Pass" gate to go green.

For details on every workflow included in this template, see CI Workflows.

6. Configure Your Project

Open Cargo.toml and update the package metadata to match your project:

[package]
name = "your_crate_name"          # already set by template-init
version = "0.1.0"
edition = "2024"
rust-version = "1.92"
description = "A short description of your crate"  # <-- update
license = "MIT"                                      # <-- update if needed
authors = ["Your Name <you@example.com>"]            # <-- update
repository = "https://github.com/you/your-repo"     # already set by template-init
keywords = ["your", "keywords"]                      # <-- update
categories = ["development-tools"]                   # <-- update

Checklist:

  • Set description to a one-line summary of your crate.
  • Set authors to the correct name and email.
  • Choose the appropriate license (MIT, Apache-2.0, or dual).
  • Update keywords (up to 5) and categories for crates.io discoverability.
  • Update README.md with your project's purpose, usage examples, and badges.

For a comprehensive configuration walkthrough, see Configuration.

7. Required Secrets

Most workflows use only the automatic GITHUB_TOKEN. Optional workflows require additional secrets configured in Settings > Secrets and variables > Actions:

Secret Required for How to obtain
GITHUB_TOKEN All workflows (CI, releases, etc.) Automatic -- provided by GitHub Actions
HOMEBREW_TAP_TOKEN Updating your Homebrew tap formula (package-homebrew.yml) Fine-grained PAT with write access to your homebrew-tap repository
CODECOV_TOKEN Uploading coverage reports (ci.yml) Codecov dashboard after linking your repo

Publishing to crates.io (publish.yml) needs no secret -- it uses crates.io Trusted Publishing (OIDC). One-time setup: on crates.io, open your crate's Settings > Trusted Publishing and add this GitHub repo with workflow publish.yml and environment copilot.

Workflows that reference missing secrets will either skip gracefully or fail with a clear error. You only need to configure a secret when you are ready to use the corresponding feature.

8. Enable Commit Signing

The template's release workflow already attaches SLSA build provenance and CycloneDX SBOM attestations to every release artifact, and container images are signed by a centralized signer workflow. To extend signing to individual commits:

Enable in branch protection:

  • Go to Settings > Branches > Branch protection rules for main.
  • Check "Require signed commits".

This ensures all commits merged into main carry a verified signature.

Contributor setup:

  • Point contributors to the Commit Signing section for SSH key or gitsign configuration.

Enable vigilant mode (recommended for maintainers):

  • Go to Settings > SSH and GPG keys on your GitHub profile.
  • Enable Vigilant mode so unsigned commits display an "Unverified" badge, making it easy to spot gaps.

9. Next Steps

You have a building, tested, CI-validated Rust project. Here is where to go from here:

  • Configuration -- Full guide to Cargo.toml, feature flags, profiles, and lints.
  • CI Workflows -- Deep dive into every workflow: triggers, secrets, and customization.
  • Customization -- How to add modules, remove the binary target, enable async, and tailor the template to your needs.
  • CONTRIBUTING.md -- Contribution guidelines for your collaborators.