From 9dbababa1beb4cc24bb2fd6d672c10ef4f72562f Mon Sep 17 00:00:00 2001 From: Connor Gilbert Date: Wed, 13 Nov 2024 17:06:06 -0800 Subject: [PATCH 1/2] Docs: Add catalog of common tools integrated with Code Quality --- doc/.vale/gitlab_base/spelling-exceptions.txt | 1 + doc/ci/testing/code_quality.md | 112 ++++++++++++++++++ 2 files changed, 113 insertions(+) diff --git a/doc/.vale/gitlab_base/spelling-exceptions.txt b/doc/.vale/gitlab_base/spelling-exceptions.txt index 8a616d3b33ec79..5d0bfa83fe7455 100644 --- a/doc/.vale/gitlab_base/spelling-exceptions.txt +++ b/doc/.vale/gitlab_base/spelling-exceptions.txt @@ -761,6 +761,7 @@ pseudonymizer Pulumi Puma Pumble +Pylint PyPI pytest Python diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 56ddb83e5bdb9f..3086543244cacb 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -184,3 +184,115 @@ For example, this is a compliant report: } ] ``` + +## Integrate common tools with Code Quality + +Many tools natively support the required [report format](#code-quality-report-format) to integrate their results with Code Quality. +They may call it a "CodeClimate report", "GitLab Code Quality report", or another similar name. + +Other tools can be configured to create JSON output by providing a custom template or format specification. +Because the [report format](#code-quality-report-format) has only a few required fields, you may be able to use this output type to create a report for Code Quality. + +If you already use a tool in your CI/CD pipeline, you should adapt the existing job to add a Code Quality report. +Adapting the existing job prevents you from running a separate job that may confuse developers and make your pipelines take longer to run. + +If you don't already use a tool, you can write a CI job from scratch or adopt the tool by using a component from [the CI/CD Catalog](../components/index.md#cicd-catalog). + +### Code scanning tools + +#### ESLint + +If you already have an [ESLint](https://eslint.org/) job in your CI/CD pipelines, you should add a report to send its output to Code Quality. +To integrate its output: + +1. Add [`eslint-formatter-gitlab`](https://www.npmjs.com/package/eslint-formatter-gitlab) as a development dependency in your project. +1. Add the `--format gitlab` option to the command you use to run ESLint. +1. Declare a [`codequality` report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) that points to the location of the report file. + - By default, the formatter reads your CI/CD configuration and infers the filename where it should save the report. + If the formatter can't infer the filename you used in your artifact declaration, set the CI/CD variable `ESLINT_CODE_QUALITY_REPORT` to the filename specified for your artifact, such as `gl-code-quality-report.json`. + +You can also use or adapt the [ESLint CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +#### MyPy + +If you already have a [MyPy](https://mypy-lang.org/) job in your CI/CD pipelines, you should add a report to send its output to Code Quality. +To integrate its output: + +1. Install [`mypy-gitlab-code-quality`](https://pypi.org/project/mypy-gitlab-code-quality/) as a dependency in your project. +1. Change your `mypy` command to send its output to a file. +1. Add a step to your job `script` to reprocess the file into the required format by using `mypy-gitlab-code-quality`. For example: + + ```yaml + - mypy $(find -type f -name "*.py" ! -path "**/.venv/**") --no-error-summary > mypy-out.txt || true # "|| true" is used for preventing job failure when mypy find errors + - mypy-gitlab-code-quality < mypy-out.txt > gl-code-quality-report.json + ``` + +1. Declare a [`codequality` report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) that points to the location of the report file. + +You can also use or adapt the [MyPy CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +#### Flake8 + +If you already have a [Flake8](https://flake8.pycqa.org/) job in your CI/CD pipelines, you should add a report to send its output to Code Quality. +To integrate its output: + +1. Install [`flake8-gl-codeclimate`](https://github.com/awelzel/flake8-gl-codeclimate) as a dependency in your project. +1. Add the arguments `--format gl-codeclimate --output-file gl-code-quality-report.json` to the command you use to run Flake8. +1. Declare a [`codequality` report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) that points to the location of the report file. + +You can also use or adapt the [Flake8 CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +#### Pylint + +If you already have a [Pylint](https://pypi.org/project/pylint/) job in your CI/CD pipelines, you should add a report to send its output to Code Quality. +To integrate its output: + +1. Install [`pylint-gitlab`](https://pypi.org/project/pylint-gitlab/) as a dependency in your project. +1. Add the argument `--output-format=pylint_gitlab.GitlabCodeClimateReporter` to the command you use to run Pylint. +1. Change your `pylint` command to send its output to a file. +1. Declare a [`codequality` report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) that points to the location of the report file. + +You can also use or adapt the [Pylint CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +#### golangci-lint + +If you already have a [`golangci-lint`](https://golangci-lint.run/) job in your CI/CD pipelines, you should add a report to send its output to Code Quality. +To integrate its output: + +1. Add the arguments `--out-format code-climate:gl-code-quality-report.json,line-number` to the command you use to run golangci-lint. +1. Declare a [`codequality` report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) that points to the location of the report file. + +You can also use or adapt the [golangci-lint CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +#### PMD Copy/Paste Detector + +The [PMD Copy/Paste Detector (CPD)](https://pmd.github.io/pmd/pmd_userdocs_cpd.html) requires additional configuration because its default output doesn't conform to the required format. + +You can use or adapt the [PMD CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +#### SwiftLint + +Using [SwiftLint](https://realm.github.io/SwiftLint/) requires additional configuration because its default output doesn't conform to the required format. + +You can use or adapt the [PMD CI/CD component](https://gitlab.com/explore/catalog/eakca1/codequality-os-scanners-integration) to run the scan and integrate its output with Code Quality. + +### Documentation scanning tools + +You can use Code Quality to scan any file stored in a repository, even if it isn't code. + +#### Vale + +If you already have a [Vale](https://vale.sh/) job in your CI/CD pipelines, you should add a report to send its output to Code Quality. +To integrate its output: + +1. Create a Vale template file in your repository that defines the required format. + - You can copy the open source [template used to check GitLab documentation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/vale-json.tmpl). + - You can also use another open source variant like the one used in the community [`gitlab-ci-utils` Vale project](https://gitlab.com/gitlab-ci-utils/container-images/vale/-/blob/main/vale/vale-glcq.tmpl). This community project also provides [a pre-made container image](https://gitlab.com/gitlab-ci-utils/container-images/vale) that includes the same template so you can use it directly in your pipelines. +1. Add the arguments `--output="$VALE_TEMPLATE_PATH" --no-exit` to the command you use to run Vale. +1. Change your `vale` command to send its output to a file. +1. Declare a [`codequality` report artifact](../yaml/artifacts_reports.md#artifactsreportscodequality) that points to the location of the report file. + +You can also use or adapt an open source job definition to run the scan and integrate its output with Code Quality, for example: + +- The [Vale linting step](https://gitlab.com/gitlab-org/gitlab/-/blob/94f870b8e4b965a41dd2ad576d50f7eeb271f117/.gitlab/ci/docs.gitlab-ci.yml#L71-87) used to check GitLab documentation. +- The community [`gitlab-ci-utils` Vale project](https://gitlab.com/gitlab-ci-utils/container-images/vale#usage). -- GitLab From 985f3fa15d90abc338afc78af271c601f15b5f1a Mon Sep 17 00:00:00 2001 From: Russell Dickenson Date: Wed, 20 Nov 2024 02:44:00 +0000 Subject: [PATCH 2/2] Apply 1 suggestion(s) to 1 file(s) --- doc/ci/testing/code_quality.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ci/testing/code_quality.md b/doc/ci/testing/code_quality.md index 3086543244cacb..5b59591f983dd0 100644 --- a/doc/ci/testing/code_quality.md +++ b/doc/ci/testing/code_quality.md @@ -196,7 +196,7 @@ Because the [report format](#code-quality-report-format) has only a few required If you already use a tool in your CI/CD pipeline, you should adapt the existing job to add a Code Quality report. Adapting the existing job prevents you from running a separate job that may confuse developers and make your pipelines take longer to run. -If you don't already use a tool, you can write a CI job from scratch or adopt the tool by using a component from [the CI/CD Catalog](../components/index.md#cicd-catalog). +If you don't already use a tool, you can write a CI/CD job from scratch or adopt the tool by using a component from [the CI/CD Catalog](../components/index.md#cicd-catalog). ### Code scanning tools -- GitLab