From 4bf6e920989eae3988aa972c204d5e23b0bcd00d Mon Sep 17 00:00:00 2001 From: Niraj Tolia Date: Fri, 19 Aug 2022 09:46:24 -0700 Subject: [PATCH] Docs text and build fixes (#613) * Fix Lint warnings in the linters docs file * Fix broken links (`make build` is no longer broken) --- docs/docs/developers/linters.md | 24 ++++++++++++------------ docs/docs/developers/testing.md | 3 ++- docs/docusaurus.config.js | 2 +- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/docs/developers/linters.md b/docs/docs/developers/linters.md index ffdd4dcc8..8f921bb83 100644 --- a/docs/docs/developers/linters.md +++ b/docs/docs/developers/linters.md @@ -21,13 +21,13 @@ in `.github/worflows/lint.yaml`. ## Running the linter -You can run the linter manually or with the Makefile in the repo. Running with -the Makefile will also ensure you have the proper version of golangci-lint +You can run the linter manually or with the `Makefile` in the repository. Running with +the `Makefile` will also ensure you have the proper version of golangci-lint installed. -### Running with the Makefile +### Running with the `Makefile` -There’s a Makefile in the repo that will automatically check if the proper +There’s a `Makefile` in the repository that will automatically check if the proper golangci-lint version is installed and run it. This make rule can be run with `make lint`. If golangci-lint isn't installed locally or the wrong version is present it will tell you what version it expects and give a link to the @@ -36,7 +36,7 @@ installation page. ### Running manually You can run golangci-lint manually by executing `golangci-lint run` in the Corso -code directory. It will automatically use the `.golangci.yml` config file so it +code directory. It will automatically use the `.golangci.yml` configuration file so it executes with the same settings as the GitHub action. ## Adding exceptions for lint errors @@ -56,13 +56,13 @@ result in the linter still reporting that line. The `golangci.yml` file has a list of issues that are ignored in the whole project. These should be as targeted as possible to avoid silencing other lint -errors that are't related to the one in question. The golangci-lint +errors that aren't related to the one in question. The golangci-lint [issues configuration page](https://golangci-lint.run/usage/configuration/#issues-configuration) has some information on this, but it's also useful to look at [existing exceptions](https://github.com/alcionai/corso/blob/main/src/.golangci.yml) -in the repo under the `issues` section. +in the repository under the `issues` section. -The config file allows for regex in the text property, so it’s useful to include +The configuration file allows for regex in the text property, so it’s useful to include the linter/rule that triggered the message. This ensures the lint error is only ignored for that linter. Combining the linter/rule with the error message text specific to that error also helps avoid ignoring other lint errors. @@ -73,13 +73,13 @@ Some linters have output messages that don't make clear what the issue is. The following subsections give the version of golangci-lint that they apply to, the linter in question, and give guidance on interpreting lint messages. -### gci `Expected 's', Found 'a' at file.go` +### `gci` `Expected 's', Found 'a' at file.go` -This applies to golangci-lint v1.45.2 for the gci linter and is due to an import -ordering issue. It occurs because imports in the file are't grouped according +This applies to golangci-lint v1.45.2 for the `gci` linter and is due to an import +ordering issue. It occurs because imports in the file aren't grouped according to the import rules for Corso. Corso code should have three distinct import groups, system imports, third party imports, and imports of other Corso code -like below. The most likely cause of a gci lint error is a Corso import in the +like below. The most likely cause of a `gci` lint error is a Corso import in the block for third party libraries. ```go diff --git a/docs/docs/developers/testing.md b/docs/docs/developers/testing.md index 12e93c3ca..3c87d4287 100644 --- a/docs/docs/developers/testing.md +++ b/docs/docs/developers/testing.md @@ -35,7 +35,8 @@ appropriate ENV variable. e.g. `CORSO_CI_TESTS=true go test ./...` -The complete list of enviroment constants is [here](../../../src/internal/tester/integration_runners.go) +The complete list of environment constants is available at +`.../src/internal/tester/integration_runners.go`. ## Advanced Options diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 18206b842..6e359cfc8 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -79,7 +79,7 @@ const config = { items: [ { label: 'Docs', - to: '/docs/intro', + to: '/intro', }, ], },