From 1b35b1fd0666d3b04d9987e5f25e1dc35c4c0440 Mon Sep 17 00:00:00 2001 From: Leynos Date: Fri, 20 Jun 2025 13:53:35 +0100 Subject: [PATCH 1/3] Clarify cache timing in setup-rust docs --- .github/actions/setup-rust/CHANGELOG.md | 7 +++ .github/actions/setup-rust/README.md | 58 +++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 .github/actions/setup-rust/CHANGELOG.md create mode 100644 .github/actions/setup-rust/README.md diff --git a/.github/actions/setup-rust/CHANGELOG.md b/.github/actions/setup-rust/CHANGELOG.md new file mode 100644 index 00000000..f30afc64 --- /dev/null +++ b/.github/actions/setup-rust/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +## v1.0.1 +- Document caching requirements, limitations and clarify when caches are saved. + +## v1.0.0 +- Initial version. diff --git a/.github/actions/setup-rust/README.md b/.github/actions/setup-rust/README.md new file mode 100644 index 00000000..1b742da8 --- /dev/null +++ b/.github/actions/setup-rust/README.md @@ -0,0 +1,58 @@ +# Setup Rust + +Install the Rust toolchain and cache your build dependencies. Optionally install +PostgreSQL system libraries for crates that require them. + +## Inputs + +| Name | Description | Required | Default | +| --- | --- | --- | --- | +| install-postgres-deps | Install PostgreSQL system dependencies | no | `false` | + +## Outputs + +None + +## Example + +```yaml +- uses: ./.github/actions/setup-rust@v1 + with: + install-postgres-deps: true +``` + +## Caching + +This action caches `~/.cargo/registry`, `~/.cargo/git` and the build output in +`target/$BUILD_PROFILE` using +[actions/cache](https://github.com/actions/cache). The cache key combines the +operating system, the `BUILD_PROFILE` environment variable and checksums of +`rust-toolchain.toml` and any `Cargo.lock` files. + +The cache is restored when this step runs and is saved **after the entire job** +finishes. Any files generated by subsequent build steps therefore become part of +the cached directories. + +### Requirements + +- Set the `BUILD_PROFILE` environment variable (`debug` or `release`) before + invoking the action so that the cache key is deterministic. + +### Extent and limitations + +- GitHub limits the total cache size to 5 GB per repository and OS, so old + entries may be evicted. +- Caches are scoped to the runner OS; Linux, macOS and Windows caches are + independent. +- The cache is best-effort: if the key changes or the cache is evicted, the + build will proceed without cached artifacts. + +### Effective use + +- Keep `rust-toolchain.toml` and `Cargo.lock` files checked in to ensure stable + cache keys. +- Set `BUILD_PROFILE` consistently across jobs. For most CI runs `release` is a + good choice. + + +Release history is available in [CHANGELOG](CHANGELOG.md). From 270e4672ef7f92e1e0322994dee5eac2f18ed6fa Mon Sep 17 00:00:00 2001 From: Leynos Date: Fri, 20 Jun 2025 14:08:55 +0100 Subject: [PATCH 2/3] docs: clarify setup-rust usage --- .github/actions/setup-rust/CHANGELOG.md | 3 +++ .github/actions/setup-rust/README.md | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/actions/setup-rust/CHANGELOG.md b/.github/actions/setup-rust/CHANGELOG.md index f30afc64..24ec7cf8 100644 --- a/.github/actions/setup-rust/CHANGELOG.md +++ b/.github/actions/setup-rust/CHANGELOG.md @@ -1,5 +1,8 @@ # Changelog +## v1.0.2 +- Document `BUILD_PROFILE` environment variable and fix README example + ## v1.0.1 - Document caching requirements, limitations and clarify when caches are saved. diff --git a/.github/actions/setup-rust/README.md b/.github/actions/setup-rust/README.md index 1b742da8..87285ef5 100644 --- a/.github/actions/setup-rust/README.md +++ b/.github/actions/setup-rust/README.md @@ -8,6 +8,7 @@ PostgreSQL system libraries for crates that require them. | Name | Description | Required | Default | | --- | --- | --- | --- | | install-postgres-deps | Install PostgreSQL system dependencies | no | `false` | +| BUILD_PROFILE | Build profile used for caching | no | `release` | ## Outputs @@ -16,7 +17,7 @@ None ## Example ```yaml -- uses: ./.github/actions/setup-rust@v1 +uses: ./.github/actions/setup-rust@v1 with: install-postgres-deps: true ``` From e9142c6bbc98d00cf52c15f1e7117df3ad598b1a Mon Sep 17 00:00:00 2001 From: Leynos Date: Fri, 20 Jun 2025 14:09:02 +0100 Subject: [PATCH 3/3] chore: address review comments --- .github/actions/setup-rust/CHANGELOG.md | 3 +++ .github/actions/setup-rust/README.md | 8 ++++---- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/actions/setup-rust/CHANGELOG.md b/.github/actions/setup-rust/CHANGELOG.md index 24ec7cf8..cfb45df0 100644 --- a/.github/actions/setup-rust/CHANGELOG.md +++ b/.github/actions/setup-rust/CHANGELOG.md @@ -1,9 +1,12 @@ + # Changelog ## v1.0.2 + - Document `BUILD_PROFILE` environment variable and fix README example ## v1.0.1 + - Document caching requirements, limitations and clarify when caches are saved. ## v1.0.0 diff --git a/.github/actions/setup-rust/README.md b/.github/actions/setup-rust/README.md index 87285ef5..0e5298f7 100644 --- a/.github/actions/setup-rust/README.md +++ b/.github/actions/setup-rust/README.md @@ -1,7 +1,7 @@ # Setup Rust -Install the Rust toolchain and cache your build dependencies. Optionally install -PostgreSQL system libraries for crates that require them. +Install the Rust toolchain and cache your build dependencies. Optionally +install PostgreSQL system libraries for crates that require them. ## Inputs @@ -43,7 +43,7 @@ the cached directories. - GitHub limits the total cache size to 5 GB per repository and OS, so old entries may be evicted. -- Caches are scoped to the runner OS; Linux, macOS and Windows caches are +- Caches are scoped to the runner OS; Linux, macOS, and Windows caches are independent. - The cache is best-effort: if the key changes or the cache is evicted, the build will proceed without cached artifacts. @@ -52,7 +52,7 @@ the cached directories. - Keep `rust-toolchain.toml` and `Cargo.lock` files checked in to ensure stable cache keys. -- Set `BUILD_PROFILE` consistently across jobs. For most CI runs `release` is a +- Set `BUILD_PROFILE` consistently across jobs. For most CI runs, `release` is a good choice.