repository template for Rust projects
chore: finish migration to Tangled
authored by
+149
-386
-5
.gitattributes
-5
.gitattributes
-31
.github/dependabot.yml
-31
.github/dependabot.yml
···
1
-
# To get started with Dependabot version updates, you'll need to specify which
2
-
# package ecosystems to update and where the package manifests are located.
3
-
# Please see the documentation for all configuration options:
4
-
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
5
-
6
-
version: 2
7
-
updates:
8
-
- package-ecosystem: "cargo"
9
-
directory: "/"
10
-
schedule:
11
-
interval: "monthly"
12
-
commit-message:
13
-
prefix: "deps(cargo):"
14
-
open-pull-requests-limit: 4
15
-
16
-
- package-ecosystem: "github-actions"
17
-
directory: "/"
18
-
schedule:
19
-
interval: "weekly"
20
-
commit-message:
21
-
prefix: "deps(gha):"
22
-
groups:
23
-
actions:
24
-
patterns:
25
-
- "actions/*"
26
-
rust:
27
-
patterns:
28
-
- "rust-lang/*"
29
-
- "Swatinem/*"
30
-
- "taiki-e/*"
31
-
open-pull-requests-limit: 4
-42
.github/workflows/audit.yml
-42
.github/workflows/audit.yml
···
1
-
name: Security audit
2
-
on:
3
-
pull_request:
4
-
paths:
5
-
- '.github/workflows/audit.yml'
6
-
- '**/Cargo.toml'
7
-
- '**/Cargo.lock'
8
-
push:
9
-
branches:
10
-
- main
11
-
paths:
12
-
- '.github/workflows/audit.yml'
13
-
- '**/Cargo.toml'
14
-
- '**/Cargo.lock'
15
-
schedule:
16
-
# Run once a week on Monday at 00:00 (12:00AM or Midnight, UTC)
17
-
# See POSIX cron syntax visualized at https://crontab.guru/#0_0_*_*_1
18
-
# GitHub Docs: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onschedule
19
-
# Cron syntax reference: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07
20
-
- cron: '0 0 * * 1'
21
-
workflow_dispatch:
22
-
23
-
jobs:
24
-
audit:
25
-
runs-on: ubuntu-latest
26
-
steps:
27
-
- name: Checkout repository
28
-
uses: actions/checkout@v6
29
-
- name: Check if Cargo.lock file exists
30
-
run: |
31
-
if [ -f "Cargo.lock" ]; then
32
-
echo "cargo_lock_exists=true" >> $GITHUB_ENV
33
-
else
34
-
echo "cargo_lock_exists=false" >> $GITHUB_ENV
35
-
fi
36
-
- name: Generate Cargo.lock if file does not exist
37
-
if: env.cargo_lock_exists == 'false'
38
-
run: cargo generate-lockfile --verbose
39
-
- name: Install cargo-audit
40
-
uses: taiki-e/install-action@cargo-audit
41
-
- name: Run cargo-audit
42
-
run: cargo audit
-67
.github/workflows/docs.yml
-67
.github/workflows/docs.yml
···
1
-
name: rustdoc
2
-
3
-
on:
4
-
push:
5
-
branches: [main]
6
-
pull_request:
7
-
branches: [main]
8
-
workflow_dispatch:
9
-
10
-
# Allow only one concurrent deployment, skipping runs queued between
11
-
# the run in-progress and latest queued. However, do NOT cancel in-progress
12
-
# runs as we want to allow these production deployments to complete.
13
-
concurrency:
14
-
group: "pages"
15
-
cancel-in-progress: false
16
-
17
-
# GitHub Pages requires a root `index.html` to function properly.
18
-
# This job does a few things to make sure this works:
19
-
# - Runs the Nightly channel of Rust
20
-
# - Passes the `--enable-index-page` flag to Rustdoc; since this
21
-
# is an unstable feature, this requires Nightly Rust and also
22
-
# passing the `-Zunstable-options` flag
23
-
#
24
-
# See:
25
-
# - https://doc.rust-lang.org/rustdoc/unstable-features.html#--enable-index-page-generate-a-default-index-page-for-docs
26
-
jobs:
27
-
build:
28
-
runs-on: ubuntu-latest
29
-
steps:
30
-
- name: Checkout repository
31
-
uses: actions/checkout@v6
32
-
- name: Install Rust
33
-
run: |
34
-
rustup set profile minimal
35
-
rustup toolchain install nightly
36
-
rustup override set nightly
37
-
- name: Compile crates
38
-
run: cargo build --verbose
39
-
- name: Build documentation
40
-
run: cargo doc --workspace --no-deps --all-features --verbose
41
-
env:
42
-
RUSTDOCFLAGS: -D warnings --cfg docsrs -Zunstable-options --enable-index-page --show-coverage
43
-
- name: Setup Pages
44
-
uses: actions/configure-pages@v5
45
-
# https://github.com/actions/deploy-pages/issues/188#issuecomment-1597651901
46
-
- name: Remove build files in /target/doc with incorrect permissions
47
-
run: rm -f ./target/doc/.lock
48
-
- name: Print build files in /target/doc
49
-
run: find ./target/doc -exec echo {} \;
50
-
- name: Upload Pages artifact
51
-
uses: actions/upload-pages-artifact@v4
52
-
with:
53
-
path: ./target/doc
54
-
deploy:
55
-
runs-on: ubuntu-latest
56
-
needs: build
57
-
if: github.event_name != 'pull_request'
58
-
permissions:
59
-
pages: write
60
-
id-token: write
61
-
environment:
62
-
name: github-pages
63
-
url: ${{ steps.deployment.outputs.page_url }}
64
-
steps:
65
-
- name: Deploy to GitHub Pages
66
-
id: deployment
67
-
uses: actions/deploy-pages@v4
-173
.github/workflows/main.yml
-173
.github/workflows/main.yml
···
1
-
name: CI
2
-
3
-
# # NOTES
4
-
#
5
-
# ## GitHub Apps
6
-
#
7
-
# To use Codecov (for uploading and analyzing code coverage), you must
8
-
# authenticate the Codecov GitHub App via https://github.com/apps/codecov.
9
-
#
10
-
# ## GitHub Actions
11
-
#
12
-
# This workflow previously used the following GitHub Actions, but no longer does:
13
-
# - `actions-rs/cargo`: See https://github.com/actions-rs/cargo/issues/216 (uses Node.js 12)
14
-
# - `actions-rs/toolchain`: See https://github.com/actions-rs/toolchain/issues/219 (uses Node.js 12)
15
-
# - `actions-rs/tarpaulin`: This seems to be shaky (non-deterministic); it will sometimes fail or pass.
16
-
#
17
-
# For `actions-rs/cargo` and `actions-rs/toolchain`, we instead use
18
-
# `cargo` and `rustup` directly in the CLI instead respectively.
19
-
#
20
-
# For `actions-rs/tarpaulin`, we instead use `cargo-llvm-codecov` via
21
-
# `taiki-e/install-action@cargo-llvm-cov`.
22
-
23
-
on:
24
-
push:
25
-
branches: [ main ]
26
-
pull_request:
27
-
28
-
concurrency:
29
-
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
30
-
cancel-in-progress: true
31
-
32
-
jobs:
33
-
build:
34
-
name: build (${{ matrix.label }})
35
-
runs-on: ubuntu-latest
36
-
strategy:
37
-
# Documentation:
38
-
# - https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs
39
-
# - https://rust-lang.github.io/rustup/concepts/channels.html
40
-
# - https://rust-lang.github.io/rustup/concepts/toolchains.html
41
-
matrix:
42
-
include:
43
-
- label: msrv
44
-
toolchain: '1.88'
45
-
- label: stable
46
-
toolchain: stable
47
-
- label: beta
48
-
toolchain: beta
49
-
- label: nightly
50
-
toolchain: nightly
51
-
52
-
steps:
53
-
- name: Checkout repository
54
-
uses: actions/checkout@v6
55
-
- name: Install Rust (${{ matrix.toolchain }})
56
-
run: |
57
-
rustup set profile minimal
58
-
rustup toolchain install ${{ matrix.toolchain }}
59
-
rustup override set ${{ matrix.toolchain }}
60
-
- name: Print environment info
61
-
run: |
62
-
rustc --version --verbose
63
-
cargo --version
64
-
rustup --version
65
-
- name: Cache dependencies
66
-
uses: Swatinem/rust-cache@v2
67
-
with:
68
-
shared-key: full-build-cache
69
-
- name: Build
70
-
run: cargo build --verbose --all-features
71
-
72
-
test:
73
-
name: test
74
-
runs-on: ubuntu-latest
75
-
76
-
steps:
77
-
- name: Checkout repository
78
-
uses: actions/checkout@v6
79
-
# `--doctests` flag for `cargo llvm-cov` requires nightly channel
80
-
# see: https://github.com/taiki-e/cargo-llvm-cov/issues/2
81
-
- name: Install Rust (Nightly)
82
-
run: |
83
-
rustup set profile minimal
84
-
rustup toolchain install nightly
85
-
rustup override set nightly
86
-
rustup component add llvm-tools-preview
87
-
- name: Print environment info
88
-
run: |
89
-
rustc --version --verbose
90
-
cargo --version
91
-
rustup --version
92
-
- name: Cache dependencies
93
-
uses: Swatinem/rust-cache@v2
94
-
with:
95
-
shared-key: full-build-cache
96
-
- name: Install cargo-llvm-codecov
97
-
uses: taiki-e/install-action@cargo-llvm-cov
98
-
- name: Generate code coverage
99
-
run: |
100
-
cargo llvm-cov \
101
-
--all-features \
102
-
--workspace \
103
-
--lcov \
104
-
--output-path lcov.info \
105
-
--doctests \
106
-
- name: Upload code coverage
107
-
uses: codecov/codecov-action@v5
108
-
with:
109
-
token: ${{ secrets.CODECOV_TOKEN }}
110
-
verbose: true
111
-
files: lcov.info
112
-
113
-
miri:
114
-
runs-on: ubuntu-latest
115
-
116
-
steps:
117
-
- name: Checkout repository
118
-
uses: actions/checkout@v6
119
-
- name: Install Rust (nightly)
120
-
run: |
121
-
rustup set profile minimal
122
-
rustup toolchain install nightly
123
-
rustup override set nightly
124
-
rustup component add miri
125
-
- name: Print environment info
126
-
run: |
127
-
rustc --version --verbose
128
-
cargo --version
129
-
rustup --version
130
-
cargo miri --version
131
-
- name: Cache dependencies
132
-
uses: Swatinem/rust-cache@v2
133
-
with:
134
-
shared-key: full-build-cache
135
-
- name: Setup Miri
136
-
run: |
137
-
cargo miri setup
138
-
- name: Run tests with Miri
139
-
run: cargo miri test
140
-
141
-
codequality:
142
-
name: codequality (${{ matrix.tool }})
143
-
runs-on: ubuntu-latest
144
-
strategy:
145
-
matrix:
146
-
include:
147
-
- tool: clippy
148
-
cmd-cargo: clippy
149
-
cmd-check: cargo clippy --all-features
150
-
- tool: rustfmt
151
-
cmd-cargo: fmt
152
-
cmd-check: cargo fmt --all -- --check
153
-
steps:
154
-
- name: Checkout repository
155
-
uses: actions/checkout@v6
156
-
- name: Install Rust
157
-
run: |
158
-
rustup set profile minimal
159
-
rustup toolchain install stable
160
-
rustup override set stable
161
-
rustup component add ${{ matrix.tool }}
162
-
- name: Print environment info
163
-
run: |
164
-
rustc --version --verbose
165
-
cargo --version
166
-
cargo ${{ matrix.cmd-cargo }} --version
167
-
rustup --version
168
-
- name: Cache dependencies
169
-
uses: Swatinem/rust-cache@v2
170
-
with:
171
-
shared-key: full-build-cache
172
-
- name: Run code quality assurance check (${{ matrix.tool }})
173
-
run: ${{ matrix.cmd-check }}
-43
.github/workflows/release.yml
-43
.github/workflows/release.yml
···
1
-
name: Publish
2
-
3
-
on:
4
-
push:
5
-
tags: ['v*']
6
-
pull_request:
7
-
branches: [ main ]
8
-
workflow_dispatch:
9
-
10
-
jobs:
11
-
publish:
12
-
name: publish
13
-
runs-on: ubuntu-latest
14
-
permissions:
15
-
id-token: write
16
-
steps:
17
-
- name: Checkout repository
18
-
uses: actions/checkout@v6
19
-
- name: Install Rust
20
-
run: |
21
-
rustup set profile minimal
22
-
rustup toolchain install stable
23
-
rustup override set stable
24
-
- name: Print environment info
25
-
run: |
26
-
rustc --version --verbose
27
-
cargo --version
28
-
rustup --version
29
-
- name: Authenticate to crates.io
30
-
if: ${{ github.event_name == 'push' }}
31
-
uses: rust-lang/crates-io-auth-action@v1
32
-
id: auth
33
-
- name: Publish
34
-
run: |
35
-
if [ "${{ github.event_name }}" = "pull_request" ]; then
36
-
echo "Dry-run publishing (PR)..."
37
-
cargo publish --verbose --workspace --dry-run
38
-
else
39
-
echo "Trusted publishing via OIDC (push)..."
40
-
cargo publish --verbose --workspace
41
-
fi
42
-
env:
43
-
CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
+25
.tangled/workflows/build.yml
+25
.tangled/workflows/build.yml
···
1
+
when:
2
+
- event: ["pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine:
6
+
- nixery
7
+
8
+
dependencies:
9
+
- cargo
10
+
- rustup
11
+
12
+
steps:
13
+
- name: Checkout repository
14
+
uses: actions/checkout@v6
15
+
- name: Setup Rust
16
+
run: |
17
+
rustup set profile minimal
18
+
rustup toolchain install stable
19
+
rustup override set stable
20
+
- name: Print environment info
21
+
run: |
22
+
cargo --version
23
+
rustup --version
24
+
- name: Build
25
+
run: cargo build --verbose --all-features
+26
.tangled/workflows/codeqa-clippy.yml
+26
.tangled/workflows/codeqa-clippy.yml
···
1
+
when:
2
+
- event: ["pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine:
6
+
- nixery
7
+
8
+
dependencies:
9
+
nixpkgs:
10
+
- cargo
11
+
- rustup
12
+
13
+
steps:
14
+
- name: Setup Rust
15
+
command: |
16
+
rustup set profile minimal
17
+
rustup toolchain install stable
18
+
rustup override set stable
19
+
rustup component add clippy
20
+
- name: Build packages
21
+
command: |
22
+
cargo --version
23
+
cargo clippy --version
24
+
rustup --version
25
+
- name: Run rustfmt checks
26
+
command: cargo clippy --all-features
+26
.tangled/workflows/codeqa-rustfmt.yml
+26
.tangled/workflows/codeqa-rustfmt.yml
···
1
+
when:
2
+
- event: ["pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine:
6
+
- nixery
7
+
8
+
dependencies:
9
+
nixpkgs:
10
+
- cargo
11
+
- rustup
12
+
13
+
steps:
14
+
- name: Setup Rust
15
+
command: |
16
+
rustup set profile minimal
17
+
rustup toolchain install stable
18
+
rustup override set stable
19
+
rustup component add rustfmt
20
+
- name: Build packages
21
+
command: |
22
+
cargo --version
23
+
cargo rustfmt --version
24
+
rustup --version
25
+
- name: Run rustfmt checks
26
+
command: cargo fmt --all -- --check
+29
.tangled/workflows/test-miri.yml
+29
.tangled/workflows/test-miri.yml
···
1
+
when:
2
+
- event: ["pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine:
6
+
- nixery
7
+
8
+
dependencies:
9
+
nixpkgs:
10
+
- cargo
11
+
- cargo-llvm-codecov
12
+
- rustup
13
+
14
+
steps:
15
+
- name: Setup Rust
16
+
command: |
17
+
rustup set profile minimal
18
+
rustup toolchain install nightly
19
+
rustup override set nightly
20
+
rustup component add llvm-tools-preview
21
+
- name: Print environment info
22
+
command: |
23
+
cargo --version
24
+
cargo miri --version
25
+
rustup --version
26
+
- name: Setup Miri
27
+
command: cargo miri setup
28
+
- name: Run tests with Miri
29
+
command: cargo miri test
+35
.tangled/workflows/test.yml
+35
.tangled/workflows/test.yml
···
1
+
when:
2
+
- event: ["pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine:
6
+
- nixery
7
+
8
+
dependencies:
9
+
nixpkgs:
10
+
- cargo
11
+
- cargo-llvm-codecov
12
+
- rustup
13
+
14
+
steps:
15
+
# `--doctests` flag for `cargo llvm-cov` requires nightly channel
16
+
# see: https://github.com/taiki-e/cargo-llvm-cov/issues/2
17
+
- name: Setup Rust
18
+
command: |
19
+
rustup set profile minimal
20
+
rustup toolchain install nightly
21
+
rustup override set nightly
22
+
rustup component add llvm-tools-preview
23
+
- name: Print environment info
24
+
command: |
25
+
rustc --version --verbose
26
+
cargo --version
27
+
rustup --version
28
+
- name: Generate code coverage
29
+
command: |
30
+
cargo llvm-cov \
31
+
--all-features \
32
+
--workspace \
33
+
--lcov \
34
+
--output-path lcov.info \
35
+
--doctests \
+1
-1
Cargo.toml
+1
-1
Cargo.toml
+1
-1
LICENSE-MIT
+1
-1
LICENSE-MIT
+5
-13
README.md
+5
-13
README.md
···
2
2
A repository template to get started with writing Rust projects.
3
3
4
4
## Features
5
-
- [x] CI/CD support with [GitHub Actions](https://github.com/features/actions)
6
-
- [x] Deploy Rustdoc documentation to GitHub Pages
5
+
- [x] CI/CD support with [Tangled](https://docs.tangled.org/spindles.html)
7
6
- [x] Run tests with LLVM code coverage
8
7
- [x] [Rustfmt](https://github.com/rust-lang/rustfmt) and [Clippy](https://github.com/rust-lang/rust-clippy) for formatting and linting
9
-
- [x] [cargo-audit](https://crates.io/crates/cargo-audit) for security auditing (by the Secure Code WG)
10
-
- [x] [Trusted Publishing](https://crates.io/docs/trusted-publishing) with OIDC (OpenID Connect)
11
8
- [x] Includes [MIT](./LICENSE-MIT) & [Apache-2.0](./LICENSE-APACHE) licenses for ecosystem compatibility (see [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/necessities.html#crate-and-its-dependencies-have-a-permissive-license-c-permissive) book)
12
9
13
10
## Getting started
14
11
### Creating a new repository
15
-
Choose a method:
16
-
- **GitHub UI**: Press the "Use this template" button in the top-right corner of this page.
17
-
- **GitHub CLI**: Install [GitHub CLI](https://cli.github.com). Then run one of the following:
18
-
```sh
19
-
gh repo create --template neoncitylights/rust --public --clone {{repository}} # clone as public
20
-
gh repo create --template neoncitylights/rust --private --clone {{repository}} # clone as private
21
-
```
12
+
1. Clone this repository template
13
+
1. In the repository directory, remove `.git` folder with `rm -rf .git`
14
+
1. In the repository directory, Initialize git repository with `git init .`
22
15
23
16
### Replace placeholders
24
17
Replace the following placeholders with your editor's find-and-replace:
···
26
19
- `{{desc}}` - The description of the library.
27
20
- `{{author}}` - The author's name of the library. For example, this could be a username, nickname, or real name.
28
21
- `{{email}}` - The author's email address. This is optional and can be deleted.
29
-
- `neoncitylights/rust` - Replace this with the name of your repository.
30
22
- `my_crate` - Replace this with the name of your crate.
31
23
32
24
## Configure
33
25
| Tool | File path | Reference |
34
26
| ---- | --------- | --------- |
35
-
| GitHub Actions CI | [`.github/workflows`](./.github/workflows) | [Reference](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) |
27
+
| Tangled CI | [`.tangled/workflows`](./.tangled/workflows) | [Reference](https://docs.tangled.org/spindles.html) |
36
28
| Cargo package | [`Cargo.toml`](./Cargo.toml) | [Reference](https://doc.rust-lang.org/cargo/reference/manifest.html) |
37
29
| Clippy (Linter) | [`.clippy.toml`](./.clippy.toml) | [Repository](https://github.com/rust-lang/rust-clippy), [Reference]( https://rust-lang.github.io/rust-clippy/) |
38
30
| Rustfmt (Formatter) | [`.rustfmt.toml`](./.rustfmt.toml) | [Repository](https://github.com/rust-lang/rustfmt), [Reference](https://rust-lang.github.io/rustfmt/) |
+1
-1
crates/my_crate/LICENSE-MIT
+1
-1
crates/my_crate/LICENSE-MIT
-9
crates/my_crate/README.md
-9
crates/my_crate/README.md
···
1
1
# {{library}}
2
2
[![License][license-badge]][license-url]
3
-
[![CI][ci-badge]][ci-url]
4
-
[![Security audit][security-badge]][security-url]
5
-
[![Codecov][codecov-badge]][codecov-url]
6
3
7
4
[license-badge]: https://img.shields.io/badge/License-MIT%20%26%20Apache%202.0-blue?style=flat-square
8
5
[license-url]: #license
9
-
[ci-badge]: https://img.shields.io/github/deployments/neoncitylights/rust/github-pages?label=deploy&style=flat-square
10
-
[ci-url]: https://github.com/neoncitylights/rust/actions/workflows/main.yml
11
-
[security-badge]: https://img.shields.io/github/actions/workflow/status/neoncitylights/rust/.github/workflows/main.yml?style=flat-square
12
-
[security-url]: https://github.com/neoncitylights/rust/actions/workflows/security-audit.yml
13
-
[codecov-badge]: https://img.shields.io/codecov/c/github/neoncitylights/rust?style=flat-square&logo=codecov&logoColor=%23fff
14
-
[codecov-url]: https://codecov.io/gh/neoncitylights/rust
15
6
16
7
{{desc}}
17
8