# Webstatus Maintenance

> Use when upgrading toolchain versions (Go, Node.js, Terraform, Playwright) or updating the DevContainer and Github CI configurations.

- Skill: `googlechrome/webstatus-maintenance` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add googlechrome/webstatus-maintenance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlechrome/webstatus-maintenance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: googlechrome (https://skillmd.com/u/googlechrome)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlechrome/webstatus-maintenance

---


# 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](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:

1. `.devcontainer/devcontainer.json` (`features -> go -> version`)
2. `.github/workflows/ci.yml` (`GO_VERSION` environment variable)
3. `.github/workflows/devcontainer.yml` (`GO_VERSION` environment variable)
4. `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:

1. `.devcontainer/devcontainer.json` (`features -> node -> version`)
2. `.devcontainer/Dockerfile` (`FROM mcr.microsoft.com/devcontainers/typescript-node:X-22`)
3. `.github/workflows/ci.yml` (`NODE_VERSION` environment variable)
4. `.github/workflows/devcontainer.yml` (`NODE_VERSION` environment variable)
5. `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:

1. Update `playwright` and `@web/test-runner-playwright` in `frontend/package.json`.
2. 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.