| name | webstatus-maintenance |
| description | Use when upgrading toolchain versions (Go, Node.js, Terraform, Playwright) or updating the DevContainer and Github CI configurations. |
webstatus-maintenance
This skill provides guidance for updating the core toolchain versions across the webstatus.dev repository.
Architecture
For a technical overview of synchronized upgrades and infrastructure maintenance, see references/architecture.md.
General Guidelines
- DO cross-reference all infrastructure/scripts against the official Google Style Guides (e.g. for Shell Scripts, YAML). If you are unsure about a specific style rule, DO NOT assume; you MUST ask the user for clarification.
Synchronized Upgrades
When asked to update a specific language or tool, you must update it in all of its respective locations to prevent environment drift.
Upgrading Go
The Go version must be kept in sync across:
.devcontainer/devcontainer.json (features -> go -> version).github/workflows/ci.yml (GO_VERSION environment variable).github/workflows/devcontainer.yml (GO_VERSION environment variable)images/go_service.Dockerfile (FROM golang:X.Y.Z-alpine...)
After updating the files, you should run make go-update && make go-tidy to ensure the go.mod dependencies are compatible with the new version.
Upgrading Go Workspace & Tools Dependencies (tools/go.mod vs go.work)
Because webstatus.dev uses a multi-module workspace (go.work), tools/go.mod (oapi-codegen, wrench, addlicense) is included right inside the active workspace when make go-workspace-setup runs:
- Synchronized
tools Upgrades: When upgrading shared libraries (like github.com/getkin/kin-openapi or runtime), you MUST also update tools/go.mod (github.com/oapi-codegen/oapi-codegen/v2) to a compatible version. Otherwise, Go's Minimal Version Selection (MVS) will compile tools against the upgraded kin-openapi models and cause type mismatch errors (mismatched types openapi3.MappingRef and string).
- Makefile
@latest Flags: Ensure targets like go-update-tools use go get -u ...@latest for all tools so they do not lag behind when running updates.
golangci-lint Configuration: When bumping golangci-lint versions across v2 config format, ensure goconst.ignore-tests: true is preserved so table-driven test fixtures are not flagged. Note that we do NOT use brittle ignore-string-values whitelists for Spanner query parameter keys (startAt, pageSize, etc.); instead, we exclude goconst specifically for lib/gcpspanner/.*\.go under linters.exclusions.rules (path: lib/gcpspanner/.*\.go), because parameter keys naturally repeat across dozens of independent query methods matching raw SQL @param bindings.
Upgrading Node.js
The Node.js version must be kept in sync across:
.devcontainer/devcontainer.json (features -> node -> version).devcontainer/Dockerfile (FROM mcr.microsoft.com/devcontainers/typescript-node:X-22).github/workflows/ci.yml (NODE_VERSION environment variable).github/workflows/devcontainer.yml (NODE_VERSION environment variable)images/nodejs_service.Dockerfile (FROM node:X.Y.Z-alpine...)
After updating, run make node-update and test the frontend build.
Upgrading Playwright
Playwright requires its NPM package and OS-level dependencies to stay in sync:
- Update
playwright and @web/test-runner-playwright in frontend/package.json.
- Update the system dependencies in
.github/workflows/ci.yml (the npx playwright install --with-deps step).
Upgrading DevContainer Features
Other DevContainer tools (Terraform, Skaffold, Shellcheck, GitHub CLI) are managed within .devcontainer/devcontainer.json.
- Find the relevant feature under the
features object and update its "version".
- If modifying Terraform, also ensure the
.terraform-version file (if one exists) or CI checks match the new version.
- Lockfile Synchronization (
devcontainer-lock.json): .devcontainer/devcontainer-lock.json is committed to version control to guarantee deterministic container builds across developers and CI (.github/workflows/devcontainer.yml) by locking exact OCI feature digests (@sha256:...) and resolved versions. Whenever you modify features or version constraints in .devcontainer/devcontainer.json, you MUST ensure .devcontainer/devcontainer-lock.json is updated and committed alongside devcontainer.json.
- To regenerate or update the lockfile locally, run
devcontainer up / devcontainer build or devcontainer features upgrade --workspace-folder . using the DevContainer CLI.
- Always stage both files:
git add .devcontainer/devcontainer.json .devcontainer/devcontainer-lock.json.
Documentation Updates
If you change how versions are managed or introduce a new critical dependency:
- Update
docs/maintenance.md to reflect the new update path.
- Trigger the "Updating the Knowledge Base" prompt in
GEMINI.md to ensure I am aware of the changes.
