eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Document checksum recovery and synthetic module cache isolation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-08 14:25:46 +00:00
parent c7942210d5
commit ae0e4a0263
3 changed files with 62 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/consumers/check.md
View File

@@ -86,6 +86,9 @@ settings are preserved, including values from Go's persistent environment
file. The check revalidates the branch, commit, and cleanliness after file. The check revalidates the branch, commit, and cleanliness after
validation. validation.
For checksum failures during dependency preparation, use the
[module checksum investigation guide](delivery.md#investigating-module-checksum-mismatches).
A successful check is evidence about the local candidate only. It does not A successful check is evidence about the local candidate only. It does not
check whether a remote branch or tag is available and does not create a tag. check whether a remote branch or tag is available and does not create a tag.
The [`check` command](../cli.md) reads the product and optional additional The [`check` command](../cli.md) reads the product and optional additional

45
docs/consumers/delivery.md
View File

@@ -214,3 +214,48 @@ move the tag to make a retry pass. See
for runner-provided tag and commit variables and for runner-provided tag and commit variables and
[workflow syntax](https://woodpecker-ci.org/docs/usage/workflow-syntax) for tag [workflow syntax](https://woodpecker-ci.org/docs/usage/workflow-syntax) for tag
events, sequential steps, and the shared workspace. events, sequential steps, and the shared workspace.
## Investigating module checksum mismatches
During tool installation or dependency preparation, a checksum mismatch means
the bytes Go read differ from a recorded checksum. The message alone does not
identify whether those bytes came from the local cache or a remote source.
Keep checksum verification enabled and retain the error, selected version,
and relevant `go.sum` entries. Go's [module authentication reference](https://go.dev/ref/mod#authenticating)
describes these checks.
To isolate a public ReleaseKit download from application settings and the
existing module cache, run the following with a compatible local Go toolchain.
Replace `v0.2.0` with the affected version. This diagnostic accesses the public
Go proxy and checksum database and retains its temporary directory for inspection.
```sh
(
checksum_dir=$(mktemp -d) || exit 1
printf 'Checksum investigation directory: %s\n' "$checksum_dir"
cd "$checksum_dir" || exit 1
GOENV=off GOFLAGS= GOWORK=off GOTOOLCHAIN=local \
GOPRIVATE= GONOPROXY= GONOSUMDB= \
GOPROXY=https://proxy.golang.org GOSUMDB=sum.golang.org \
GOMODCACHE="$checksum_dir/modules" \
go mod download -json gitea.maximumdirect.net/eric/ReleaseKit@v0.2.0
)
```
A successful isolated download establishes that this version verifies through
the selected proxy. Compare its `GoMod`, `GoModSum`, and `Sum` with the affected
cache and the application's recorded checksums. Locate the original cache with
`go env GOMODCACHE`; Go stores downloaded module metadata separately from the
extracted source. See the [module cache reference](https://go.dev/ref/mod#module-cache).
Once a stale cache entry is confirmed, preserve a copy, quarantine that entry
while no Go process is using it, and retry normal dependency preparation. For
a confirmed stale `.mod`, quarantine that file alone. Preserve application
checksums and published tags. Routine downloads can continue to use the normal
module cache.
If the isolated download also fails, investigate the selected proxy, tagged
source, and recorded checksums with the maintainer before changing local state.
Record any difference between proxy and direct fetching. A confirmed cache
problem can be repaired locally; changes to published source follow the
maintainer's immutable-release procedure.

14
docs/development.md
View File

@@ -75,3 +75,17 @@ validation. The [maintainer release procedure](release.md) owns preparation,
publication, and recovery. Hosted note-page delivery is a separate prepared publication, and recovery. Hosted note-page delivery is a separate prepared
workflow and does not change the successful-tag-push completion point. ReleaseKit workflow and does not change the successful-tag-push completion point. ReleaseKit
does not declare binary deliverables. does not declare binary deliverables.
## Testing synthetic modules
Tests that serve synthetic module versions through local proxies should pass a
test-owned temporary `GOMODCACHE` to every Go subprocess that consumes those
versions. Scope fixture-specific proxy and checksum settings to those processes.
This applies the [testing policy's isolation requirements](policy/testing.md#test-execution-requirements)
to module downloads and keeps fixture metadata out of developer and CI caches.
Distinct fixture version numbers still occupy the real module's cache namespace.
Use temporary caches even when the selected versions have never been published.
Verify isolation at the shared fixture boundary; ordinary builds can continue
to use their prepared dependency cache. Consumer recovery guidance lives in the
[module checksum investigation guide](consumers/delivery.md#investigating-module-checksum-mismatches).