diff --git a/docs/src/config/sidebar.yml b/docs/src/config/sidebar.yml index c9ae7130..93030648 100644 --- a/docs/src/config/sidebar.yml +++ b/docs/src/config/sidebar.yml @@ -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 diff --git a/docs/src/docs/product/changelog.mdx b/docs/src/docs/product/changelog.mdx new file mode 100644 index 00000000..79c20185 --- /dev/null +++ b/docs/src/docs/product/changelog.mdx @@ -0,0 +1,7 @@ +--- +title: Changelog +--- + +## Changelog + +{.ChangeLog} diff --git a/docs/src/docs/usage/performance.mdx b/docs/src/docs/product/performance.mdx similarity index 100% rename from docs/src/docs/usage/performance.mdx rename to docs/src/docs/product/performance.mdx diff --git a/docs/src/docs/product/roadmap.mdx b/docs/src/docs/product/roadmap.mdx index feb8c409..dcca3c88 100644 --- a/docs/src/docs/product/roadmap.mdx +++ b/docs/src/docs/product/roadmap.mdx @@ -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 diff --git a/docs/src/docs/usage/configuration.mdx b/docs/src/docs/usage/configuration.mdx index f3546439..969c0bc6 100644 --- a/docs/src/docs/usage/configuration.mdx +++ b/docs/src/docs/usage/configuration.mdx @@ -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 diff --git a/docs/src/docs/usage/install/annotations.png b/docs/src/docs/welcome/annotations.png similarity index 100% rename from docs/src/docs/usage/install/annotations.png rename to docs/src/docs/welcome/annotations.png diff --git a/docs/src/docs/usage/faq.mdx b/docs/src/docs/welcome/faq.mdx similarity index 98% rename from docs/src/docs/usage/faq.mdx rename to docs/src/docs/welcome/faq.mdx index a4805eba..680c80f5 100644 --- a/docs/src/docs/usage/faq.mdx +++ b/docs/src/docs/welcome/faq.mdx @@ -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. diff --git a/docs/src/docs/usage/install/index.mdx b/docs/src/docs/welcome/install.mdx similarity index 61% rename from docs/src/docs/usage/install/index.mdx rename to docs/src/docs/welcome/install.mdx index efd13f6c..f998f6c3 100644 --- a/docs/src/docs/usage/install/index.mdx +++ b/docs/src/docs/welcome/install.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). diff --git a/docs/src/docs/usage/integrations.mdx b/docs/src/docs/welcome/integrations.mdx similarity index 100% rename from docs/src/docs/usage/integrations.mdx rename to docs/src/docs/welcome/integrations.mdx diff --git a/docs/src/docs/usage/quick-start.mdx b/docs/src/docs/welcome/quick-start.mdx similarity index 71% rename from docs/src/docs/usage/quick-start.mdx rename to docs/src/docs/welcome/quick-start.mdx index 2894998c..e5b1139f 100644 --- a/docs/src/docs/usage/quick-start.mdx +++ b/docs/src/docs/welcome/quick-start.mdx @@ -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/). diff --git a/scripts/website/dump_info/main.go b/scripts/website/dump_info/main.go index 5f7b8eeb..599981ea 100644 --- a/scripts/website/dump_info/main.go +++ b/scripts/website/dump_info/main.go @@ -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) diff --git a/scripts/website/expand_templates/main.go b/scripts/website/expand_templates/main.go index 5f2157a9..e2951f3f 100644 --- a/scripts/website/expand_templates/main.go +++ b/scripts/website/expand_templates/main.go @@ -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 } diff --git a/scripts/website/types/types.go b/scripts/website/types/types.go index 2eeabf3f..955c6c43 100644 --- a/scripts/website/types/types.go +++ b/scripts/website/types/types.go @@ -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 {