Skip to content

fix(deps): update module go.yaml.in/yaml/v3 to v4 - #403

Merged
masutaka merged 1 commit into
mainfrom
renovate/go.yaml.in-yaml-v3-4.x
Nov 17, 2026
Merged

masutaka merged 1 commit into
mainfrom
renovate/go.yaml.in-yaml-v3-4.x

Conversation

@renovate

@renovate renovate Bot commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

This PR contains the following updates:

Package Change Age Confidence
go.yaml.in/yaml/v3 v3.0.6 → v4.0.0 age confidence

Release Notes

yaml/go-yaml (go.yaml.in/yaml/v3)

v4.0.0: go-yaml v4.0.0

Compare Source

go-yaml v4.0.0

go-yaml v4.0.0 is the first stable release of the v4 series, maintained by the
YAML organization.
It adds configurable loading and dumping, public plugin interfaces, structured
errors, and a CLI for inspecting YAML processing.
The classic APIs remain supported, so applications can adopt v4 incrementally.

Getting started

Install the release:

go get go.yaml.in/yaml/v4@v4.0.0

Use this import path in your Go code:

import "go.yaml.in/yaml/v4"

For an existing v3 application, start by updating imports, reviewing custom
unmarshalers, and running your tests.
You can continue using Unmarshal, Marshal, NewDecoder, and NewEncoder.
The v2 and v3 APIs remain frozen, with security fixes only; new features and
routine bug fixes are developed in v4.

Why add Load and Dump?

Applications need different YAML policies: strict configuration validation,
particular output layouts, or custom anchor handling.
The new Load and Dump functions and streaming Loader and Dumper accept
functional options and plugins for those choices.
They use YAML's load/dump terminology and are recommended for new code.

The classic entry points keep compatibility settings rather than changing
formatting and error presentation for every existing caller.
Moving to the new API is an explicit choice to use v4 defaults, with presets
available when you want older settings.
Classic APIs remain supported.

For example, load a configuration with strict field checking, then choose its
output indentation:

package main

import (
    "fmt"
    "log"

    "go.yaml.in/yaml/v4"
)

func main() {
    var config struct {
        Name string `yaml:"name"`
        Port int    `yaml:"port"`
    }
    input := []byte("name: api\nport: 8080\n")
    if err := yaml.Load(input, &config, yaml.WithKnownFields()); err != nil {
        log.Fatal(err)
    }
    output, err := yaml.Dump(config, yaml.WithIndent(4))
    if err != nil {
        log.Fatal(err)
    }
    fmt.Print(string(output))
}

Unknown struct fields are ignored by default; WithKnownFields() opts into
rejecting them.
Duplicate mapping keys are rejected by default.
Options apply in order, so later options override earlier settings.

Defaults and compatibility

Setting Classic Marshal / Unmarshal Load / Dump defaults
Output indentation 4 spaces 2 spaces
Sequence indentation Non-compact Compact
Quote preference Legacy mixed quoting Single quotes where possible
Preferred output width Unlimited for Marshal 80 characters
Error presentation v3 style v4 style with stage and position

Quoting still depends on scalar content and styles, and line width is a
preference rather than a guaranteed maximum.
NewDecoder uses v3 error formatting; NewEncoder retains v3 output settings
with v4 error formatting.

Choose WithV3Defaults() to select compatibility defaults through the new API.
When replacing Marshal, also disable wrapping to match its line-width setting:

output, err := yaml.Dump(config,
    yaml.WithV3Defaults(),
    yaml.WithLineWidth(-1),
)

Presets select defaults; they do not reverse every v4 bug fix or reproduce every
legacy code path.
For example, package-level Load requires exactly one document, whereas
Unmarshal retains legacy handling of empty input and trailing content.
WithSingleDocument() deliberately skips validation of later documents.
Use WithAllDocuments() to load or dump slices as document streams, or use a
streaming loader or dumper to process documents individually.

Options, plugins, and nodes

Options control indentation, sequence layout, quoting, document markers,
Unicode escaping, field validation, and more.
OptsYAML accepts YAML configuration for supported settings, which can also be
shared with the CLI.

The public plugin APIs cover six areas:

  • Loader-Limits: configure depth and alias expansion checks.
  • Merge-Key: control merge directives and mapping conflicts, or replace the
    merge algorithm.
  • Alias-Data: supply external anchors, retain anchors across documents, use
    dotted paths, or reject alias references.
  • Error-format: select error presentation or implement a custom formatter.
  • YAML-parser: select an alternative parser implementation.
  • Tab-indent: opt into tab-aware input and output indentation.

The core module provides implementations for these APIs.
Additional parsers live in separate modules, keeping their dependencies optional.
Existing depth and alias protections remain enabled by default.

yaml.Node gives access to tags, styles, comments, anchors, and source positions.
Node.Load and Node.Dump accept options for node conversion.
Pass construction options explicitly inside custom unmarshaler hooks;
Node.Load starts with fresh defaults independently of its calling loader.
Stream nodes can expose encoding and YAML directives.
Node output retains supported styles and comments without promising identical
source formatting.

Migration details to check

NewLoader and NewDumper return errors; check them before using the stream.
Check dumper Dump and Close errors as well.

Custom UnmarshalYAML(*yaml.Node) error hooks must use the v4 node type.
Recognized v3 node hooks produce a migration error rather than silently losing
custom behavior.
The legacy UnmarshalYAML(func(any) error) error callback remains supported.

Conversion failures return structured *yaml.LoadErrors values.
Use errors.As to inspect structured errors or match legacy *yaml.TypeError
values, rather than relying on a direct type assertion or fixed message text.

Review the migration guide
for the complete compatibility guidance.

Inspect YAML with the CLI

Install the CLI from this release:

go install go.yaml.in/yaml/v4/cmd/go-yaml@v4.0.0

Convert to JSON, inspect nodes, or examine scanner and parser output:

go-yaml -J config.yaml
go-yaml -N config.yaml
go-yaml -T config.yaml
go-yaml -E config.yaml

The CLI also supports reusable options files and pipelines between intermediate
stages, making small bug reports easier to reproduce.
Runtime plugin selection chooses implementations already linked into the binary.

Further reading and thanks

See the options guide,
plugin guide,
CLI guide,
and API reference.
Please report problems with minimal input, a reproducer, and your Go version in
the issue tracker.

Release-candidate users should update to v4.0.0 and rerun their tests, as some APIs
changed during prerelease development.
Thanks to everyone who tested, reported problems, and contributed to this release.


Configuration

📅 Schedule: (in timezone Asia/Tokyo)

  • Branch creation
    • On day 1 and 16 of the month (* * 1,16 * *)
  • Automerge
    • At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.


  • If you want to rebase/retry this PR, check this box

This PR was generated by Mend Renovate. View the repository job log.

@renovate
renovate Bot requested a review from masutaka as a code owner November 15, 2026 16:58
@renovate renovate Bot added dependencies Pull requests that update a dependency file go Pull requests that update Go code labels Nov 15, 2026
@github-actions

Copy link
Copy Markdown
Contributor

PR 403: fix(deps): update module go.yaml.in/yaml/v3 to v4

Summary

  • Package: go.yaml.in/yaml/v3 v3.0.6 → go.yaml.in/yaml/v4 v4.0.0
  • Dependency type: Runtime dependency (direct require in go.mod)
  • Version change: Major (v3 → v4; the module path changes, so the import path is changed too)

Key Findings

  • Breaking Changes: Yes in general, but they should not affect this repository.
    • v4 adds the new Load / Dump APIs with different defaults (2-space indent, compact sequences, an 80-column line width, a v4 error format). The release notes say the classic Marshal / Unmarshal / NewDecoder / NewEncoder APIs keep compatibility settings.
    • Migration notes cover custom UnmarshalYAML(*yaml.Node) hooks (these must use the v4 node type), structured *yaml.LoadErrors (use errors.As instead of a direct *yaml.TypeError assertion), and the NewLoader / NewDumper error returns.
    • This repository calls only yaml.Unmarshal([]byte(content), s) once (lib/settings.go:65). The target is the plain Settings struct: no custom unmarshaler, no yaml tags, and no type assertions on the returned error. None of the migration items apply.
  • Security: None. There are no open Dependabot alerts in this repository, and this PR is a regular version upgrade, not a security fix. The v2/v3 lines stay frozen and get security fixes only, so staying on v3 is still supported for now.
  • Supported versions: No impact. The v4.0.0 go.mod declares go 1.18, and this repository uses go 1.26.0 / toolchain go1.27.3.
  • CI status: In progress when checked.
    • Passed: test (ubuntu-latest), dependency_review, gh_action_lint (ghalint / jactionlint / zizmor), codeql / Filter Paths, renovate/stability-days
    • Pending: test (macos-latest), test (windows-latest), codeql / languages (go), review_deps_pr / review
    • Note: TestInit in lib/settings_test.go is skipped ("This test is pending."), so no test exercises the YAML parsing path. Passing tests show that the code compiles, not that settings are parsed correctly.
  • Cascading updates: None. go.sum swaps the go.yaml.in/yaml/v3 v3.0.6 hashes for the go.yaml.in/yaml/v4 v4.0.0 hashes. The remaining go.yaml.in/yaml/v3 v3.0.4/go.mod line was there before and is unchanged; it comes from another module's dependency graph. The go.mod / go.sum diff shows no other dependency changes.

Impact

  • Only lib/settings.go uses this package, and only to parse settings.yml. That file comes from the user's Gist or from the embedded default (config/settings.yml via statik) and is parsed into Settings (Format.Subject, Format.Line, Dictionary.Status.Merged, Dictionary.Status.Closed).
  • Settings has no yaml tags, so it relies on the default lowercased field-name mapping (format, subject, dictionary, ...). The classic Unmarshal is documented to keep v3-compatible behavior. If that mapping changed, the formatting settings would silently fall back to empty values without an error, so this is worth a quick manual check (see below).
  • Nothing in the library marshals YAML, so v4's output-format changes (indentation, quoting, line width) do not matter here.
  • Upstream diff (supplementary): compare/v3.0.6...v4.0.0 is diverged (563 commits ahead, 13 behind). The commits list was truncated at 250 and the files list at 236 files. Among the visible commits, most are by the maintainer ingydotnet (160), followed by dependabot[bot] and regular contributors. The GitHub release v4.0.0 was published by ingydotnet on 2026-11-04 and is not a prerelease. No suspicious change was found in what could be checked, but the size of the diff made a full review impossible.

Unverified Items

  • The runtime behavior of yaml.Unmarshal with the actual default settings.yml and a Gist settings.yml under v4 was not checked. Running github-nippou once, or checking that Settings.Format.Subject / Format.Line / Dictionary.Status.* are populated, would confirm the field-name mapping.
  • The macOS / Windows tests and CodeQL (go) were still pending when this review was written.
  • The upstream compare exceeded the GitHub API limit (250 commits), so not all 563 commits were reviewed. Contents published to the Go module proxy are protected by go.sum / sumdb, but whether they match the git tag was not checked independently.

Conclusion

No issues found (merge after the pending CI jobs pass)

This is a major version bump, but the repository only uses the classic yaml.Unmarshal on a plain struct, and v4 keeps that API compatible. The only code change is the import path, the minimum Go version is satisfied, and there are no cascading dependency changes. There is no security urgency, since there are no related Dependabot alerts. Because TestInit is skipped, a quick manual check that settings still load correctly is recommended before merging.

@masutaka
masutaka merged commit 4bdd08b into main Nov 17, 2026
15 checks passed
@masutaka
masutaka deleted the renovate/go.yaml.in-yaml-v3-4.x branch November 17, 2026 12:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file go Pull requests that update Go code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant