Documentation
¶
Overview ¶
Package sites implements the literal-replacement half of the coordinated Go SDK/toolchain version bump (issue #280, design.md D-4/D-5/D-6): an explicit, enumerated registry of every plain-string Go version pin the GoRuntimeUpgrader provider cannot reach (workflow GO_VERSION env vars, Go source fallback constants, and documentation), plus a plan-then-mutate engine that resolves every registered Site before writing anything.
Compile classifies malformed anchors (E4) and unsafe paths (E5) without touching the filesystem. Plan validates the target version (E6), then reads and matches every Site, aggregating every failure (E1-E3) into one returned error that names every failing path — it never writes a file. Apply performs the writes; it is the caller's contract to invoke it only after a Plan for the same site set returned no error.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Sites = []Site{
{Path: ".github/workflows/ci.yml", Anchor: "GO_VERSION: '{{V}}'", Occurrences: 1},
{Path: ".github/workflows/release-provider-go.yml", Anchor: "GO_VERSION: '{{V}}'", Occurrences: 1},
{Path: ".github/workflows/release-provider-rust.yml", Anchor: "GO_VERSION: '{{V}}'", Occurrences: 1},
{Path: "providers/go/gobuilder.go", Anchor: `const defaultGoVersion = "{{V}}"`, Occurrences: 1},
{Path: "internal/config/config.go", Anchor: `DefaultGoVersion = "{{V}}"`, Occurrences: 1},
{Path: "internal/app/step_handlers.go", Anchor: `goVersion = "{{V}}"`, Occurrences: 1},
{Path: "internal/executors/docker_executor.go", Anchor: `goVersion = "{{V}}"`, Occurrences: 1},
{Path: "internal/pipelines/test/gotester.go", Anchor: "default to {{V}} if not set", Occurrences: 1},
{Path: "internal/pipelines/test/gotester.go", Anchor: `goVersion = "{{V}}"`, Occurrences: 1},
{Path: "internal/pipelines/shared/tests.go", Anchor: `(e.g., "{{V}}").`, Occurrences: 1},
{Path: "internal/pipelines/shared/tests.go", Anchor: `goVersion = "{{V}}"`, Occurrences: 1},
{Path: "internal/pipelines/shared/builder.go", Anchor: `(e.g., "1.21", "{{V}}").`, Occurrences: 1},
{Path: "docs/CONFIGURATION.md", Anchor: "go_version: {{V}}", Occurrences: 4},
{Path: "docs/CONFIGURATION.md", Anchor: "`SHIPWRIGHT_GO_VERSION` | Go version to use | `{{V}}` | `1.24.0` |", Occurrences: 1},
{Path: "docs/CONFIGURATION.md", Anchor: "base_image: golang:{{V}}-alpine", Occurrences: 1},
{Path: "docs/LOCAL_USAGE.md", Anchor: `go_version: "{{V}}"`, Occurrences: 1},
{Path: "docs/LOCAL_USAGE.md", Anchor: "SHIPWRIGHT_PIPELINE_GO_VERSION={{V}}", Occurrences: 1},
{Path: "docs/WORKFLOW_GUIDE.md", Anchor: `goVersion: "{{V}}"`, Occurrences: 2},
{Path: "docs/INTEGRATION_GUIDE.md", Anchor: `go_version: "{{V}}"`, Occurrences: 1},
{Path: "docs/PIPELINE_DEVELOPMENT.md", Anchor: `From("golang:{{V}}-alpine").`, Occurrences: 1},
{Path: "docs/PRD.md", Anchor: "Go `{{V}}` per `go.mod`/`.go-version`", Occurrences: 1},
{Path: "docs/ANALYSIS_AND_RECOMMENDATIONS.md", Anchor: "GO_VERSION: '{{V}}'", Occurrences: 2},
{Path: "docs/ANALYSIS_AND_RECOMMENDATIONS.md", Anchor: "go-version: '{{V}}'", Occurrences: 2},
{Path: "docs/ANALYSIS_AND_RECOMMENDATIONS.md", Anchor: "golang:{{V}}", Occurrences: 4},
{Path: "docs/PRODUCTION_DEPLOYMENT.md", Anchor: "image: golang:{{V}}", Occurrences: 1},
}
Sites is the production literal-replacement registry (issue #280, design.md D-5): every plain-string Go version pin that GoRuntimeUpgrader's go.mod/go.work/.go-version handling cannot reach. Populated from a fresh, full-repo audit (not the design doc's prior list, which three earlier SDD phases each found incomplete) and cross- checked against D-7's exclusions: nothing under providers/go/testdata/runtime/**, and .dagger/release_test.go and testing/integration/go/integration_test.go stay deliberately unregistered (they assert behavior, not the repo's pin).
Decision (tasks.md 1.2): the illustrative doc-comment literals in internal/pipelines/shared/builder.go, internal/pipelines/shared/tests.go, and internal/pipelines/test/gotester.go ARE registered. They are cheap to keep in sync, each one currently restates the real fallback default used a few lines below it (not an arbitrary format example), and a removed/reformatted comment is caught loudly by E2 rather than silently going stale.
Two categories found during the census that were deliberately left OUT of this registry, because their literals do not track "the" current pin:
- "or later"/"or superior" minimum-version floors (docs/PRODUCTION_DEPLOYMENT.md's "Go 1.21 or later", docs/LOCAL_USAGE.md's "Go 1.25.5 o superior instalado") state a support floor, not the exact toolchain pin; a bump does not necessarily need to raise them in lockstep.
- docs/MERGE_CONFLICT_RESOLUTION.md's two GO_VERSION literals (1.25.1 / 1.25.2) are a worked git-conflict-marker example that deliberately shows two DIFFERENT values; forcing both to the same target would corrupt the example it's illustrating, not fix a pin.
- docs/CONFIGURATION.md's "Example" table column (`1.24.0`), docs/INTEGRATION_GUIDE.md's `go-version: ['1.25.5', '1.26.1']` test matrix, internal/pipelines/options.go's and internal/config/validation.go's format examples (`1.24.2`, `1.25`) are illustrative syntax samples that do not equal the repo's actual current pin and are not meant to track it.
Newly found during this pass, absent from every prior SDD phase's list: internal/executors/docker_executor.go's goVersion fallback (identical pattern to the three already-known fallback sites), and the exact set of anchors within docs/ANALYSIS_AND_RECOMMENDATIONS.md and docs/PRODUCTION_DEPLOYMENT.md (design.md's open question named the files; this registry is the first pass to enumerate their anchors).
Functions ¶
func Apply ¶
Apply writes every Edit's New content to its Path under root, preserving the existing file's mode. Apply performs no validation of its own — this package does not enforce call order — so it is the caller's contract to invoke Apply only with the edits returned by a Plan call that returned a nil error for the same site set, never with a partial or hand-built edit list.
func Compile ¶
Compile builds the anchored regexp for Site s. It classifies E4 (malformed anchor: zero or more than one "{{V}}" placeholder) and E5 (unsafe path: absolute, escapes the repo root, or contains a "testdata" path segment) without touching the filesystem — path safety is knowable from Site.Path alone, so Compile is the natural place to check it, ahead of Plan's file-level checks.
Types ¶
type Edit ¶
Edit is a planned, not-yet-written mutation: Path's full new file contents after every one of its Site's matched version substrings has been replaced by the target version. Edit is only ever produced by Plan.
func Plan ¶
Plan validates target's format (E6) before touching any site, then resolves every registered site: Compile the anchor, read the file, classify E1 (missing/non-regular/symlink path), E2 (zero matches), or E3 (match count mismatch). Every site's failure is aggregated into a single returned error naming every failing path — Plan never writes a file.
type Site ¶
type Site struct {
// Path is repo-root relative. It must not be absolute, must not
// escape the repo root, and must not contain a "testdata" path
// segment (D-7 layer 2).
Path string
// Anchor is the exact literal text surrounding the version
// substring, with the version itself replaced by the placeholder
// "{{V}}". Anchor must contain exactly one "{{V}}" occurrence.
Anchor string
// Occurrences is the exact number of times Anchor (with its version
// substring resolved) is expected to match inside Path. A count of
// zero is always an error (E2); any other mismatch is E3.
Occurrences int
}
Site declares one anchored literal-replacement location whose Go version substring must track the repository's canonical toolchain version.
Source Files