feat: migration command

[ldez]

I want to explain my journey on this topic because it was not an easy one.

My first thought was to try to keep comments by using several YAML parsing libs, but it was very complex, only for YAML (we should handle YAML, TOML, JSON), and at the end it was not working mainly due to the migration path of some elements.

So I gave up on migrating the comments.

I tried to use the v2 configuration structures directly, but it's not possible to serialize the configuration as expected (even with additional struct tags), mainly because of default non-zero values (e.g. boolean true by default, explicit 0 or false, ...). So it didn't work.

My next try was the working solution: using a clone of the v2 configuration that uses pointer for builtin types and struct tags.

I created a "cloner" which clones the v2 configuration structures (only) and modifies them by changing types and adds struct tags.
So the "cloned" configuration structures can be recreated if needed (make clone_config).

The solution is stable, maintainable, and tested, but I'm sad that I couldn't find a solution to keep the comments.

The migration file format is based on the extension of the configuration file.
The format can be overridden by using --format flag. (ex: golangci-lint migrate --format yml)

Before the migration, the previous configuration file is copied and saved to a file named <config_file_name>.bck.<config_file_extention>.

By default, before the migration process the configuration file is validated on the JSONSchema of the configuration v1.
If you want to skip this validation, you can use --skip-validation. (ex: golangci-lint migrate --skip-validation)

Some notable elements

The migration command also enforced some new default values:

• run.timeout: the existing value is ignored, because, in v2, by default, there is no timeout.
• issues.show-stats: the existing value is ignored, in v2, by default, the stats are enabled.
• run.concurrency: if the existing value was 0, as it's the new default, the key is removed.
• run.relative-path-mode: if the existing value was cfg, as it's the new default, the key is removed.

issues.exclude-generated has a new default value (v1 lax, v2 strict), then this field will be added during the migration to keep the previous behavior.

issues.exclude-dirs-use-default has been removed, so this is converted to linters.exclusions.paths and, if needed, formatters.exclusions.paths.

Deprecated options from the v1 or unknown fields are not migrated.

Other fields, which are explicitly defined in the configuration file, are migrated even if the value is the same as the default value.

A migration guide will be added to the documentation #5439

I created more than 150 test configuration files, and added dedicated tests on complex migration paths.

The command documentation will be added to the migration guide.

Migrate configuration file from v1 to v2

Usage:
  golangci-lint migrate [flags]

Flags:
  -c, --config PATH       Read config from file path PATH
      --no-config         Don't read config file
      --format string     By default, the file format is based on the configuration file extension.
                          Overrides file format detection.
                          It can be 'yml', 'yaml', 'toml', 'json'.
      --skip-validation   Skip validating the configuration file against the JSON schema of the v1.

Global Flags:
  -h, --help           Help for a command

[bombsimon]

Nice!! I've yet to review the individual migrations but everything else looks great! I don't think there's much to add for the rest of the code given all the tests but I saw you did a great job on documenting all permutations of enabled and disabled linters that I plan to give an extra read.

🔥

[alexandear]

Awesome work.

Left some comments.

Will take a look again later today, still need to review few files.

[bombsimon]

Awesome, LGTM

[SuperSandro2000]

Did you think about using the new omitzero tag from go 1.24?

We used that in https://github.com/majewsky/gg . See sapcc/keppel#489 as an example where we used it.

[ldez]

Did you think about using the new omitzero tag from go 1.24?

Yes, but:

1. We need to compile with go1.23
2. it doesn't solve default non-zero value (true, 8, etc.)
3. my implementation is simple, no plumbing