docs: organize sections and pages (#4493)

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/"
+      link: "/welcome/integrations/"
-    - label: "Linters"
+    - label: "FAQ"
-      link: "/usage/linters/"
+      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

docs/src/docs/product/changelog.mdx

@@ -0,0 +1,7 @@
+---
+title: Changelog
+---
+
+## Changelog
+
+{.ChangeLog}

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
 

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

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.

docs/src/docs/welcome/install.mdx

@@ -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).

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/).

scripts/website/dump_info/main.go

@@ -106,7 +106,6 @@ func saveCLIHelp(dst string) error {
 
 	data := types.CLIHelp{
 		Enable: string(lintersOutParts[0]),
-		Disable: string(lintersOutParts[1]),
 		Help:   string(shortHelp),
 	}
 

scripts/website/expand_templates/main.go

@@ -165,7 +165,6 @@ func buildTemplateContext() (map[string]string, error) {
 		"LintersExample":                  snippets.LintersSettings,
 		"ConfigurationExample":            snippets.ConfigurationFile,
 		"LintersCommandOutputEnabledOnly": helps.Enable,
-		"LintersCommandOutputDisabledOnly": helps.Disable,
 		"EnabledByDefaultLinters":         getLintersListMarkdown(true),
 		"DisabledByDefaultLinters":        getLintersListMarkdown(false),
 		"DefaultExclusions":               exclusions,

scripts/website/types/types.go

@@ -6,7 +6,6 @@ import (
 
 type CLIHelp struct {
 	Enable string `json:"enable"`
-	Disable string `json:"disable"`
 	Help   string `json:"help"`
 }