diff --git a/docs/src/config/sidebar.yml b/docs/src/config/sidebar.yml index c9ae71301866..93030648c859 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 000000000000..79c2018512b9 --- /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 feb8c409e391..dcca3c88fbce 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 f354643968e0..969c0bc62387 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 a4805eba9dfc..680c80f5c6b9 100644 --- a/docs/src/docs/usage/faq.mdx +++ b/docs/src/docs/welcome/faq.mdx @@ -2,33 +2,9 @@ title: FAQ --- -## How do you add a custom linter? - -You can integrate it yourself, see this [manual](/contributing/new-linters/). -Or you can create a [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate when time permits. - -## How to integrate `golangci-lint` into large project with thousands of issues - -We are sure that every project can easily integrate `golangci-lint`, even the large one. - -The idea is to not fix all existing issues. Fix only newly added issue: issues in new code. -To do this setup CI to run `golangci-lint` with option `--new-from-rev=HEAD~1`. - -Also, take a look at option `--new`, but consider that CI scripts that generate unstaged files will make `--new` only point out issues in those files and not in the last commit. -In that regard `--new-from-rev=HEAD~1` is safer. - -By doing this you won't create new issues in your code and can choose fix existing issues (or not). - -## Why `--new-from-rev` or `--new-from-patch` don't seem to be working in some cases? - -The options `--new-from-rev` and `--new-from-patch` work by comparing `git diff` output and issues. - -If an issue is not reported as the same line as the changes then the issue will be skipped. -This is the line of the issue is not inside the lines changed. +## Which Go versions are supported -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. +The same as the Go team (the 2 latest minor versions). ## How to use `golangci-lint` in CI @@ -36,21 +12,12 @@ Run `golangci-lint` in CI and check the exit code. If it's non-zero - fail the b 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. @@ -77,3 +44,36 @@ How to troubleshoot: - [ ] 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/). +Or you can create a [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate when time permits. + +## How to integrate `golangci-lint` into large project with thousands of issues + +We are sure that every project can easily integrate `golangci-lint`, even the large one. + +The idea is to not fix all existing issues. Fix only newly added issue: issues in new code. +To do this setup CI to run `golangci-lint` with option `--new-from-rev=HEAD~1`. + +Also, take a look at option `--new`, but consider that CI scripts that generate unstaged files will make `--new` only point out issues in those files and not in the last commit. +In that regard `--new-from-rev=HEAD~1` is safer. + +By doing this you won't create new issues in your code and can choose fix existing issues (or not). + +## Why `--new-from-rev` or `--new-from-patch` don't seem to be working in some cases? + +The options `--new-from-rev` and `--new-from-patch` work by comparing `git diff` output and issues. + +If an issue is not reported as the same line as the changes then the issue will be skipped. +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. 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 efd13f6c8e69..f998f6c38b9b 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 2894998c0fc8..e5b1139f7aac 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 5f7b8eeb6700..599981ea50ae 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 5a7b3b5e4b1f..0e6a84c361fe 100644 --- a/scripts/website/expand_templates/main.go +++ b/scripts/website/expand_templates/main.go @@ -150,18 +150,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 2eeabf3ffafb..955c6c4331cf 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 {