diff --git a/docs/src/docs/product/roadmap.mdx b/docs/src/docs/product/roadmap.mdx index bde8e4463942..dcca3c88fbce 100644 --- a/docs/src/docs/product/roadmap.mdx +++ b/docs/src/docs/product/roadmap.mdx @@ -14,6 +14,56 @@ Please file an issue for bugs, missing documentation, or unexpected behavior. [See Bugs](https://github.com/golangci/golangci-lint/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22bug%22+sort%3Acreated-desc) +## Versioning Policy + +`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool, +it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy: + +- Patch release (intended to not break your lint build) +- A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors. +- A bug fix to the CLI or core (packages loading, runner, postprocessors, etc). +- Improvements to documentation. +- Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage. +- Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone). +- Minor release (might break your lint build because of newly found issues) +- A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors. +- A new linter is added. +- An existing configuration option or linter is deprecated. +- A new CLI command is created. +- Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers. +- Major release (likely to break your lint build) +- Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default. +- A linter is removed. + +According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix). +As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds. + +For example, in our [GitHub Action](https://github.com/golangci/golangci-lint-action) we require users to explicitly set the minor version of `golangci-lint` +and we always use the latest patch version. + +## Linter Deprecation Cycle + +A linter can be deprecated for various reasons, e.g. the linter stops working with a newer version of Go or the author has abandoned its linter. + +The deprecation of a linter will follow 3 phases: + +1. **Display of a warning message**: The linter can still be used (unless it's completely non-functional), but it's recommended to remove it from your configuration. +2. **Display of an error message**: At this point, you should remove the linter. The original implementation is replaced by a placeholder that does nothing. +3. **Removal of the linter** from golangci-lint. + +Each phase corresponds to a minor version: + +- v1.0.0 -> warning message +- v1.1.0 -> error message +- v1.2.0 -> linter removed + +The deprecated linters are removed from presets immediately when they are deprecated (phase 1). + +We will provide clear information about those changes on different supports: changelog, logs, social network, etc. + +We consider the removal of a linter as non-breaking changes for golangci-lint itself. +No major version will be created when a linter is removed. + ## Future Plans 1. Upstream all changes of forked linters. diff --git a/docs/src/docs/usage/install/index.mdx b/docs/src/docs/usage/install/index.mdx index efd13f6c8e69..f998f6c38b9b 100644 --- a/docs/src/docs/usage/install/index.mdx +++ b/docs/src/docs/usage/install/index.mdx @@ -124,56 +124,6 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@{.LatestVersion} -## Versioning Policy - -`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool, -it's not always clear when a minor or major version bump occurs. To help clarify this for everyone, we've defined the following semantic versioning policy: - -- Patch release (intended to not break your lint build) - - A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors. - - A bug fix to the CLI or core (packages loading, runner, postprocessors, etc). - - Improvements to documentation. - - Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage. - - Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone). -- Minor release (might break your lint build because of newly found issues) - - A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors. - - A new linter is added. - - An existing configuration option or linter is deprecated. - - A new CLI command is created. - - Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers. -- Major release (likely to break your lint build) - - Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default. - - A linter is removed. - -According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix). -As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds. - -For example, in our [GitHub Action](https://github.com/golangci/golangci-lint-action) we require users to explicitly set the minor version of `golangci-lint` -and we always use the latest patch version. - -## Linter Deprecation Cycle - -A linter can be deprecated for various reasons, e.g. the linter stops working with a newer version of Go or the author has abandoned its linter. - -The deprecation of a linter will follow 3 phases: - -1. **Display of a warning message**: The linter can still be used (unless it's completely non-functional), but it's recommended to remove it from your configuration. -2. **Display of an error message**: At this point, you should remove the linter. The original implementation is replaced by a placeholder that does nothing. -3. **Removal of the linter** from golangci-lint. - -Each phase corresponds to a minor version: - -- v1.0.0 -> warning message -- v1.1.0 -> error message -- v1.2.0 -> linter removed - -The deprecated linters are removed from presets immediately when they are deprecated (phase 1). - -We will provide clear information about those changes on different supports: changelog, logs, social network, etc. - -We consider the removal of a linter as non-breaking changes for golangci-lint itself. -No major version will be created when a linter is removed. - ## Next [Quick Start: how to use `golangci-lint`](/usage/quick-start).