docs: organize sections and pages (#4493)
This commit is contained in:
Ludovic Fernandez
GitHub
parent
4adac529cb
commit
d736d092f6
docs/src
config
docs
scripts/website
@ -2,32 +2,36 @@
|
||||
|
||||
- label: "Introduction"
|
||||
link: "/"
|
||||
- label: Usage
|
||||
- label: Welcome
|
||||
items:
|
||||
- label: "Install"
|
||||
link: "/usage/install/"
|
||||
link: "/welcome/install/"
|
||||
- label: "Quick Start"
|
||||
link: "/usage/quick-start/"
|
||||
link: "/welcome/quick-start/"
|
||||
- label: "Integrations"
|
||||
link: "/usage/integrations/"
|
||||
- label: "Linters"
|
||||
link: "/usage/linters/"
|
||||
link: "/welcome/integrations/"
|
||||
- label: "FAQ"
|
||||
link: "/welcome/faq/"
|
||||
- label: Usage
|
||||
items:
|
||||
- label: "Configuration"
|
||||
link: "/usage/configuration/"
|
||||
- label: "Linters"
|
||||
link: "/usage/linters/"
|
||||
- label: "False Positives"
|
||||
link: "/usage/false-positives/"
|
||||
- label: "Performance"
|
||||
link: "/usage/performance/"
|
||||
- label: "FAQ"
|
||||
link: "/usage/faq/"
|
||||
- label: Product
|
||||
items:
|
||||
- label: "Roadmap"
|
||||
link: "/product/roadmap/"
|
||||
- label: "Thanks"
|
||||
link: "/product/thanks/"
|
||||
- label: "Trusted By"
|
||||
link: "/product/trusted-by/"
|
||||
- label: "Changelog"
|
||||
link: "/product/changelog/"
|
||||
- label: "Roadmap"
|
||||
link: "/product/roadmap/"
|
||||
- label: "Performance"
|
||||
link: "/product/performance/"
|
||||
- label: "GitHub"
|
||||
link: "https://github.com/golangci/golangci-lint"
|
||||
- label: Contributing
|
||||
|
||||
7
docs/src/docs/product/changelog.mdx
Normal file
7
docs/src/docs/product/changelog.mdx
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Changelog
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
{.ChangeLog}
|
||||
@ -14,9 +14,55 @@ 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)
|
||||
|
||||
## Changelog
|
||||
## Versioning Policy
|
||||
|
||||
{.ChangeLog}
|
||||
`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
|
||||
|
||||
|
||||
@ -31,6 +31,8 @@ You can configure specific linters' options only within the config file (not the
|
||||
There is a [`.golangci.reference.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.reference.yml) file with all supported options, their description, and default values.
|
||||
This file is neither a working example nor a recommended configuration, it's just a reference to display all the configuration options.
|
||||
|
||||
The configuration file can be validated with the JSON Schema: https://golangci-lint.run/jsonschema/golangci.jsonschema.json
|
||||
|
||||
{ .ConfigurationExample }
|
||||
|
||||
## Command-Line Options
|
||||
|
||||
|
Before 
(image error) Size: 145 KiB After 
(image error) Size: 145 KiB
|
@ -2,6 +2,54 @@
|
||||
title: FAQ
|
||||
---
|
||||
|
||||
## Which Go versions are supported
|
||||
|
||||
The same as the Go team (the 2 latest minor versions).
|
||||
|
||||
## How to use `golangci-lint` in CI
|
||||
|
||||
Run `golangci-lint` in CI and check the exit code. If it's non-zero - fail the build.
|
||||
|
||||
See [how to properly install `golangci-lint` in CI](/usage/install#ci-installation)
|
||||
|
||||
## `golangci-lint` doesn't work
|
||||
|
||||
1. Please, ensure you are using the latest binary release.
|
||||
2. Run it with `-v` option and check the output.
|
||||
3. If it doesn't help create a [GitHub issue](https://github.com/golangci/golangci-lint/issues/new) with the output from the error and #2 above.
|
||||
|
||||
## Why do you have `typecheck` errors?
|
||||
|
||||
`typecheck` is like a front-end for the Go compiler errors.
|
||||
Compilation errors are identified/labeled as reports of `typecheck` but they are not produced by a linter called `typecheck`.
|
||||
|
||||
`typecheck` is not a linter, it doesn't perform any analysis,
|
||||
it's just a way to identify, parse, and display compiling errors (produced by the `types.Checker`) and some linter errors.
|
||||
|
||||
It cannot be disabled because of that.
|
||||
|
||||
Of course, this is just as good as the compiler itself and a lot of compilation issues will not properly show where in the code your error lies.
|
||||
|
||||
As a consequence, the code to analyze should compile.
|
||||
It means that if you try to run an analysis on a single file or a group of files or a package or a group of packages,
|
||||
with dependencies on other files or packages of your project, as it doesn't compile (because of the missing pieces of code),
|
||||
it also cannot be analyzed.
|
||||
|
||||
If there are `typecheck` errors, golangci-lint will not able to produce other reports because that kind of error doesn't allow it to perform any analysis.
|
||||
|
||||
How to troubleshoot:
|
||||
|
||||
- [ ] Ensure the version of `golangci-lint` is built with a compatible version of Go.
|
||||
- [ ] Ensure dependencies are up-to-date with `go mod tidy`.
|
||||
- [ ] Ensure building works with `go run ./...`/`go build ./...` - whole package.
|
||||
- [ ] Ensure you are not running an analysis on code that depends on files/packages outside the scope of the analyzed elements.
|
||||
- [ ] If using CGO, ensure all require system libraries are installed.
|
||||
|
||||
## Why running with `--fast` is slow on the first run
|
||||
|
||||
Because the first run caches type information. All subsequent runs will be fast.
|
||||
Usually this options is used during development on local machine and compilation was already performed.
|
||||
|
||||
## How do you add a custom linter?
|
||||
|
||||
You can integrate it yourself, see this [manual](/contributing/new-linters/).
|
||||
@ -29,51 +77,3 @@ This is the line of the issue is not inside the lines changed.
|
||||
To fix that you have to use the option `--whole-files`.
|
||||
|
||||
The side effect is the issues inside file that contains changes but not directly related to the changes themselves will be reported.
|
||||
|
||||
## How to use `golangci-lint` in CI
|
||||
|
||||
Run `golangci-lint` in CI and check the exit code. If it's non-zero - fail the build.
|
||||
|
||||
See [how to properly install `golangci-lint` in CI](/usage/install#ci-installation)
|
||||
|
||||
## Which Go versions are supported
|
||||
|
||||
The same as the Go team (the 2 last minor versions)
|
||||
|
||||
## `golangci-lint` doesn't work
|
||||
|
||||
1. Please, ensure you are using the latest binary release.
|
||||
2. Run it with `-v` option and check the output.
|
||||
3. If it doesn't help create a [GitHub issue](https://github.com/golangci/golangci-lint/issues/new) with the output from the error and #2 above.
|
||||
|
||||
## Why running with `--fast` is slow on the first run
|
||||
|
||||
Because the first run caches type information. All subsequent runs will be fast.
|
||||
Usually this options is used during development on local machine and compilation was already performed.
|
||||
|
||||
## Why do you have `typecheck` errors?
|
||||
|
||||
`typecheck` is like a front-end for the Go compiler errors.
|
||||
Compilation errors are identified/labeled as reports of `typecheck` but they are not produced by a linter called `typecheck`.
|
||||
|
||||
`typecheck` is not a linter, it doesn't perform any analysis,
|
||||
it's just a way to identify, parse, and display compiling errors (produced by the `types.Checker`) and some linter errors.
|
||||
|
||||
It cannot be disabled because of that.
|
||||
|
||||
Of course, this is just as good as the compiler itself and a lot of compilation issues will not properly show where in the code your error lies.
|
||||
|
||||
As a consequence, the code to analyze should compile.
|
||||
It means that if you try to run an analysis on a single file or a group of files or a package or a group of packages,
|
||||
with dependencies on other files or packages of your project, as it doesn't compile (because of the missing pieces of code),
|
||||
it also cannot be analyzed.
|
||||
|
||||
If there are `typecheck` errors, golangci-lint will not able to produce other reports because that kind of error doesn't allow it to perform any analysis.
|
||||
|
||||
How to troubleshoot:
|
||||
|
||||
- [ ] Ensure the version of `golangci-lint` is built with a compatible version of Go.
|
||||
- [ ] Ensure dependencies are up-to-date with `go mod tidy`.
|
||||
- [ ] Ensure building works with `go run ./...`/`go build ./...` - whole package.
|
||||
- [ ] Ensure you are not running an analysis on code that depends on files/packages outside the scope of the analyzed elements.
|
||||
- [ ] If using CGO, ensure all require system libraries are installed.
|
||||
@ -124,56 +124,6 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@{.LatestVersion}
|
||||
|
||||
</div>
|
||||
|
||||
## 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).
|
||||
@ -22,23 +22,17 @@ golangci-lint run dir1 dir2/... dir3/file1.go
|
||||
|
||||
Directories are NOT analyzed recursively. To analyze them recursively append `/...` to their path.
|
||||
|
||||
GolangCI-Lint can be used with zero configuration. By default the following linters are enabled:
|
||||
GolangCI-Lint can be used with zero configuration. By default, the following linters are enabled:
|
||||
|
||||
```sh
|
||||
$ golangci-lint help linters
|
||||
{.LintersCommandOutputEnabledOnly}
|
||||
```
|
||||
|
||||
and the following linters are disabled by default:
|
||||
|
||||
```sh
|
||||
$ golangci-lint help linters
|
||||
...
|
||||
{.LintersCommandOutputDisabledOnly}
|
||||
```
|
||||
|
||||
Pass `-E/--enable` to enable linter and `-D/--disable` to disable:
|
||||
|
||||
```sh
|
||||
golangci-lint run --disable-all -E errcheck
|
||||
```
|
||||
|
||||
More information about available linters can be found in the [linters page](/usage/linters/).
|
||||
@ -105,9 +105,8 @@ func saveCLIHelp(dst string) error {
|
||||
shortHelp := bytes.Join(helpLines[2:], []byte("\n"))
|
||||
|
||||
data := types.CLIHelp{
|
||||
Enable: string(lintersOutParts[0]),
|
||||
Disable: string(lintersOutParts[1]),
|
||||
Help: string(shortHelp),
|
||||
Enable: string(lintersOutParts[0]),
|
||||
Help: string(shortHelp),
|
||||
}
|
||||
|
||||
return saveToJSONFile(dst, data)
|
||||
|
||||
@ -161,18 +161,17 @@ func buildTemplateContext() (map[string]string, error) {
|
||||
}
|
||||
|
||||
return map[string]string{
|
||||
"CustomGCLReference": pluginReference,
|
||||
"LintersExample": snippets.LintersSettings,
|
||||
"ConfigurationExample": snippets.ConfigurationFile,
|
||||
"LintersCommandOutputEnabledOnly": helps.Enable,
|
||||
"LintersCommandOutputDisabledOnly": helps.Disable,
|
||||
"EnabledByDefaultLinters": getLintersListMarkdown(true),
|
||||
"DisabledByDefaultLinters": getLintersListMarkdown(false),
|
||||
"DefaultExclusions": exclusions,
|
||||
"ThanksList": getThanksList(),
|
||||
"RunHelpText": helps.Help,
|
||||
"ChangeLog": string(changeLog),
|
||||
"LatestVersion": latestVersion,
|
||||
"CustomGCLReference": pluginReference,
|
||||
"LintersExample": snippets.LintersSettings,
|
||||
"ConfigurationExample": snippets.ConfigurationFile,
|
||||
"LintersCommandOutputEnabledOnly": helps.Enable,
|
||||
"EnabledByDefaultLinters": getLintersListMarkdown(true),
|
||||
"DisabledByDefaultLinters": getLintersListMarkdown(false),
|
||||
"DefaultExclusions": exclusions,
|
||||
"ThanksList": getThanksList(),
|
||||
"RunHelpText": helps.Help,
|
||||
"ChangeLog": string(changeLog),
|
||||
"LatestVersion": latestVersion,
|
||||
}, nil
|
||||
}
|
||||
|
||||
|
||||
@ -5,9 +5,8 @@ import (
|
||||
)
|
||||
|
||||
type CLIHelp struct {
|
||||
Enable string `json:"enable"`
|
||||
Disable string `json:"disable"`
|
||||
Help string `json:"help"`
|
||||
Enable string `json:"enable"`
|
||||
Help string `json:"help"`
|
||||
}
|
||||
|
||||
type ExcludePattern struct {
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user