Skip to content

Commit a46631c

Browse files
committed
docs: move version policy and depraction cycle to roadmap
1 parent 12cae07 commit a46631c

File tree

2 files changed

+50
-50
lines changed

2 files changed

+50
-50
lines changed

docs/src/docs/product/roadmap.mdx

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,56 @@ Please file an issue for bugs, missing documentation, or unexpected behavior.
1414

1515
[See Bugs](https://github.com/golangci/golangci-lint/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22bug%22+sort%3Acreated-desc)
1616

17+
## Versioning Policy
18+
19+
`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool,
20+
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:
21+
22+
- Patch release (intended to not break your lint build)
23+
- A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors.
24+
- A bug fix to the CLI or core (packages loading, runner, postprocessors, etc).
25+
- Improvements to documentation.
26+
- Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
27+
- Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
28+
- Minor release (might break your lint build because of newly found issues)
29+
- A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors.
30+
- A new linter is added.
31+
- An existing configuration option or linter is deprecated.
32+
- A new CLI command is created.
33+
- Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers.
34+
- Major release (likely to break your lint build)
35+
- Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default.
36+
- A linter is removed.
37+
38+
According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix).
39+
As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds.
40+
41+
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`
42+
and we always use the latest patch version.
43+
44+
## Linter Deprecation Cycle
45+
46+
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.
47+
48+
The deprecation of a linter will follow 3 phases:
49+
50+
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.
51+
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.
52+
3. **Removal of the linter** from golangci-lint.
53+
54+
Each phase corresponds to a minor version:
55+
56+
- v1.0.0 -> warning message
57+
- v1.1.0 -> error message
58+
- v1.2.0 -> linter removed
59+
60+
The deprecated linters are removed from presets immediately when they are deprecated (phase 1).
61+
62+
We will provide clear information about those changes on different supports: changelog, logs, social network, etc.
63+
64+
We consider the removal of a linter as non-breaking changes for golangci-lint itself.
65+
No major version will be created when a linter is removed.
66+
1767
## Future Plans
1868

1969
1. Upstream all changes of forked linters.

docs/src/docs/usage/install/index.mdx

Lines changed: 0 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -124,56 +124,6 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@{.LatestVersion}
124124

125125
</div>
126126

127-
## Versioning Policy
128-
129-
`golangci-lint` follows [semantic versioning](https://semver.org). However, due to the nature of `golangci-lint` as a code quality tool,
130-
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:
131-
132-
- Patch release (intended to not break your lint build)
133-
- A patch version update in a specific linter that results in `golangci-lint` reporting fewer errors.
134-
- A bug fix to the CLI or core (packages loading, runner, postprocessors, etc).
135-
- Improvements to documentation.
136-
- Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
137-
- Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
138-
- Minor release (might break your lint build because of newly found issues)
139-
- A major or minor version update of a specific linter that results in `golangci-lint` reporting more errors.
140-
- A new linter is added.
141-
- An existing configuration option or linter is deprecated.
142-
- A new CLI command is created.
143-
- Backward incompatible change of configuration with extremely low impact, e.g. adding validation of a list of enabled `go-critic` checkers.
144-
- Major release (likely to break your lint build)
145-
- Backward incompatible change of configuration with huge impact, e.g. removing excluding issues about missed comments from `golint` by default.
146-
- A linter is removed.
147-
148-
According to our policy, any minor update may report more errors than the previous release (ex: from a bug fix).
149-
As such, we recommend using the fixed minor version and fixed or the latest patch version to guarantee the results of your builds.
150-
151-
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`
152-
and we always use the latest patch version.
153-
154-
## Linter Deprecation Cycle
155-
156-
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.
157-
158-
The deprecation of a linter will follow 3 phases:
159-
160-
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.
161-
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.
162-
3. **Removal of the linter** from golangci-lint.
163-
164-
Each phase corresponds to a minor version:
165-
166-
- v1.0.0 -> warning message
167-
- v1.1.0 -> error message
168-
- v1.2.0 -> linter removed
169-
170-
The deprecated linters are removed from presets immediately when they are deprecated (phase 1).
171-
172-
We will provide clear information about those changes on different supports: changelog, logs, social network, etc.
173-
174-
We consider the removal of a linter as non-breaking changes for golangci-lint itself.
175-
No major version will be created when a linter is removed.
176-
177127
## Next
178128

179129
[Quick Start: how to use `golangci-lint`](/usage/quick-start).

0 commit comments

Comments
 (0)