一键导入
bump-config-version
// Freeze the current `pkg/config/latest` package as a numbered, immutable `pkg/config/vN`, then bump `latest` to the next version so new features can land on the work-in-progress schema
// Freeze the current `pkg/config/latest` package as a numbered, immutable `pkg/config/vN`, then bump `latest` to the next version so new features can land on the work-in-progress schema
| name | bump-config-version |
| description | Freeze the current `pkg/config/latest` package as a numbered, immutable `pkg/config/vN`, then bump `latest` to the next version so new features can land on the work-in-progress schema |
The agent config schema is versioned. Each numbered package
(pkg/config/v0, pkg/config/v1, …, pkg/config/vN) is frozen and
must never change. New features always land on pkg/config/latest, which
holds the next, unreleased version.
This skill freezes whatever currently lives in pkg/config/latest as
pkg/config/vN, then re-opens latest for vN+1 work. Run it whenever a
released version of the schema needs to be locked down before the next round
of breaking changes.
Note: Throughout this skill, N represents the current version number (e.g., 9),
and vN represents the version package name (e.g., v9). Replace these placeholders
with the actual numbers when executing commands.
Read the version constant:
grep '^const Version' pkg/config/latest/types.go
It looks like const Version = "N". Call this number N. The new latest
version will be N+1.
Sanity-check that pkg/config/vN does not already exist:
test ! -d pkg/config/vN && echo "ok"
If it exists, the freeze has already happened — stop and ask the user.
vN PackageCopy every Go file from latest/ into the new directory. This includes:
types.go, parse.go, auth.go, lifecycle.go, model_ref.go, validate.go)*_test.go)The new directory is created on the fly by cp:
cp -R pkg/config/latest pkg/config/vN
Rewrite the package name in all Go files (including tests) under the new directory:
# macOS / BSD sed requires -i '' (empty backup extension)
find pkg/config/vN -name '*.go' -exec sed -i '' 's/^package latest$/package vN/' {} +
Do not touch the previous import in pkg/config/vN/parse.go. It
already points at vN-1 and that is exactly what the frozen vN upgrader
needs in order to migrate vN-1 → vN.
latest for vN+1Three edits, all in pkg/config/latest/:
Bump the version constant in types.go:
const Version = "N+1"
Point the previous import in parse.go at the just-frozen package:
previous "github.com/docker/docker-agent/pkg/config/vN"
If latest/parse.go's upgradeIfNeeded contains migration logic
beyond the bare types.CloneThroughJSON(old, &config) (e.g. field
renames or shape rewrites that converted vN-1 → N), that migration is
already correctly preserved in pkg/config/vN/parse.go thanks to step 2.
Reset latest/parse.go's upgrader to the no-op CloneThroughJSON body
so it starts fresh for vN → vN+1. If latest/parse.go was already a
no-op, leave it alone.
Edit pkg/config/versions.go to import and register vN. Both
modifications are inserted just before the latest lines so registrations
stay in numerical order:
import (
// ...
vN_minus_1 "github.com/docker/docker-agent/pkg/config/vN-1"
vN "github.com/docker/docker-agent/pkg/config/vN" // ← new
)
func versions() (...) {
// ...
vN_minus_1.Register(parsers, &upgraders)
vN.Register(parsers, &upgraders) // ← new
latest.Register(parsers, &upgraders)
// ...
}
agent-schema.jsonThe JSON schema is hand-maintained but tracked alongside the Go types. Three small edits:
Update the top-level description field:
"description": "Configuration schema for Docker Agent vN+1"
Append "N+1" to the enum array under the top-level version
property.
Append "N+1" to the examples array under the same property.
Keep the existing entries — older versions remain valid input.
After editing, validate the JSON is well-formed:
jq empty agent-schema.json
Run the project's standard validation chain. All must pass:
task build
task test
task lint
Pay special attention to:
pkg/config/schema_test.go (the schema/Go-types matcher) — failures here
usually mean step 5 was missed or latest types changed shape relative
to what got frozen into vN.pkg/config/*_test.go that hard-codes version: "N" in YAML
fixtures may need to be retargeted to "N+1" if the assertion is about
the latest schema.If anything fails, fix it and re-run until everything is green.
Match the convention used by previous freeze commits in the repo
(Freeze v7, freeze config v8 and start v9 as latest):
git add -A
git commit -m "freeze config vN and start vN+1 as latest" -m "" -m "Assisted-By: docker-agent"
Report back to the user with:
vN).vN+1).pkg/config/vN/.pkg/config/latest/types.go,
pkg/config/latest/parse.go, pkg/config/versions.go,
agent-schema.json).task build, task test, and task lint all
succeeded.