What the agent does
The agent first finds how much of yaml.v2 the code really uses, because a project that only calls yaml.Unmarshal into structs migrates by changing one import and a project with custom unmarshalers does not. In a tool like pressly/sup, only supfile.go imports gopkg.in/yaml.v2 (pinned at v2.2.8 in a go.mod that says go 1.13). That file has one yaml.Unmarshal call and four UnmarshalYAML methods. Three of them, on Networks, Commands and Targets, decode the same mapping twice: once into a Go map and once into a yaml.MapSlice, only to remember the order the keys were written in. The fourth, on EnvList, decodes into []yaml.MapItem and turns every value into a string with fmt.Sprintf("%v", v.Value).
The repository has no test files, so go test ./... prints [no test files] for all three packages and proves nothing. The agent writes a small probe test before it changes the import. The test parses example/Supfile and a second document made of awkward values, and prints the names in order and every environment variable. On yaml.v2 the example gives five networks in file order (local, dev, stg, prod, k8s), nineteen commands, and six variables. The awkward document shows what %v has been doing: DEBUG: yes becomes DEBUG=true, MODE: 0755 becomes MODE=493, RATIO: 1e3 becomes RATIO=1000, an empty value becomes the text <nil>, and a key written ON becomes a variable named true.
Changing the import to gopkg.in/yaml.v3 produces exactly four compiler errors, three undefined: yaml.MapSlice and one undefined: yaml.MapItem, since v3 removed both types. The old method signature, UnmarshalYAML(unmarshal func(interface{}) error), still compiles. That invites the wrong fix: declare a yaml.Node, pass it to the old unmarshal function, and walk its Content. It builds, it returns no error, and the node comes back empty, so the example file parses to zero networks, zero commands and no variables. The probe test catches that at once. The working port changes each method to v3's own signature, UnmarshalYAML(node *yaml.Node) error, calls node.Decode for the map, and reads keys and values from node.Content in pairs.
With that port the example file parses to the same output as before, line for line. The awkward document does not, and the agent reports each difference instead of hiding it. A node carries the text as written, so yes stays yes, 0755 stays 0755, 1e3 stays 1e3 and an empty value becomes an empty string. An alias such as B: *v needs care: the node's Value is the anchor name, not the text it points to, so the port follows node.Alias or decodes the value node into a string. v3 also refuses a mapping with the same key twice when it decodes into a map (mapping key "a" already defined at line 3), where v2 accepted it and listed the command twice.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Go module from gopkg.in/yaml.v2 to gopkg.in/yaml.v3. Read go.mod and every file that imports the package. List each use: Unmarshal, Marshal, Decoder and Encoder options, custom UnmarshalYAML and MarshalYAML methods, yaml.MapSlice, yaml.MapItem, and decoding into interface{} or map[interface{}]interface{}. Before changing anything, write a probe test that parses every example config in the repository plus one document with these values: yes, no, on, off, 0755, 1e3, an empty value, a quoted string, a duplicate key, an anchor with an alias, and a badly indented line. Run it on v2 and save the output. Then port: use the v3 signature UnmarshalYAML(node *yaml.Node) error for every custom unmarshaler, never pass a yaml.Node to the old unmarshal callback, and resolve aliases. Run the probe again and report every line that differs, saying for each whether a user's existing config file would now behave differently. Keep the probe as a real test with the v3 output as its expectation. Run go build, go vet, go test and go mod tidy. Do not change the go directive unless the build needs it. Open a pull request with both probe outputs in the description.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that edits supfile.go, go.mod and go.sum, and adds one test file where there were none. The parser gets shorter, since each ordered type decodes its map once and reads the key order from the same node. go mod tidy leaves the go 1.13 line alone and records gopkg.in/yaml.v3 v3.0.1. The description shows the probe output on both versions and a short table of the values that changed.
That table is what the reviewer decides on. Passing 0755 through as text instead of the decimal 493 is almost certainly what the author of a deploy file meant. An empty variable no longer exporting the string <nil> reads as a bug fix. But they are changes to what reaches a remote shell, and a team with existing files should hear about them in the release notes. The duplicate key error is the other one: a file that used to load with a silently repeated command now stops with a line number.
The reviewer also sees one thing the port did not touch. A YAML syntax error is reported at a different line by the two parsers for the same broken file (line 4 on v2, line 2 on v3 for the probe's bad indent), so any documentation that quotes an error message needs the same update.
Run it on every GitHub issue labelled yaml-v3
In an org with many Go services, open one tracking issue per repository and let the label start the work. Add an automation to each repository's Project with a github trigger on issues.labeled, set its labels filter to yaml-v3, and save the prompt above. Only a label added by an owner, member or collaborator of the repository fires it. The issue is placed after the prompt as event text, so the saved prompt remains the instruction and the issue can carry local notes, such as which example files matter most.
An automation has a cap of 1 to 30 runs per hour that you set. An event past the cap creates a queued run that starts when the hour has room, up to one more hour's worth of waiting runs; an event beyond that is refused. Label a large batch in groups no bigger than twice the cap.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The risk in this migration is in data, not in code. Both versions compile, both parse the example file, and the difference appears only for a value like 0755 in somebody's real config. Finding that takes running the same documents through both parsers and reading two outputs side by side. The agent does that in its own sandbox with the commands recorded, so the claim "the example parses identically" in the pull request is backed by output a reviewer can open.
It also guards against the port that looks finished. The empty-node version of this change compiles cleanly, passes go vet and would pass review by diff alone in a repository with no tests. A run that is told to write the probe first cannot produce that pull request, because its own check fails on the first try.
Frequently asked questions
What replaces yaml.MapSlice in yaml.v3?
Nothing with the same name. v3 exposes the parsed document as yaml.Node, and a mapping node's Content holds its keys and values alternately, in file order. Code that used MapSlice to keep order reads the pairs from there.
Why does my custom UnmarshalYAML return empty data after the upgrade?
Most likely it kept the v2 signature and decodes into a yaml.Node through the old unmarshal callback. That compiles in v3 and yields a node with no content, without an error. Switch the method to UnmarshalYAML(node *yaml.Node) error and use the node it is given.
Is gopkg.in/yaml.v3 still maintained?
The go-yaml/yaml repository on GitHub is archived, and v3.0.1 is the last tag published at that import path. The YAML organization maintains a fork that publishes the same API as go.yaml.in/yaml/v3. Moving from v2 to v3 first is still the larger step, since the fork keeps v3's types; changing the import path afterwards is a search and replace the agent can do in the same run if you ask.
Do yes and no still parse as booleans?
When the target is a Go bool field, yes. When the target is interface{} or a node, v3 keeps them as the strings that were written, where v2 produced true and false.
More jobs like this: Upgrade dependencies weekly
- Migrate From github.com/golang/protobuf to google.golang.org/protobuf (golang/protobuf)
- Replace Deprecated golint With revive, go vet and staticcheck in a Go Project (golint)
- Migrate a Custom Environment From OpenAI Gym to Gymnasium (OpenAI Gym)
- Migrate From the Deprecated @hapi/joi Package to joi (@hapi/joi)
- Migrate an Express App From Jade to Pug (Jade)
- Migrate a Java Project From Joda-Time to java.time (Joda-Time)