From 5d346db6a58b8040ed53554dd95c0eb5553213b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Tue, 26 Oct 2021 13:00:25 +0200 Subject: [PATCH] docs: generating reports, onboarding strategy --- .vale/styles/RedHat/Headings.yml | 5 +- modules/end-user-guide/nav.adoc | 5 +- .../pages/reporting-vale-alerts.adoc | 18 +++++ ...ted-with-vale.adoc => using-vale-cli.adoc} | 8 +- ...nerating-extended-vale-alerts-reports.adoc | 40 ++++++++++ .../partials/proc_using-vale-in-the-ide.adoc | 1 - ...roc_using-vale-on-a-local-environment.adoc | 6 +- ...f_defining-a-vale-onboarding-strategy.adoc | 76 ++++++++++++------- tools/report_vale_alerts.sh | 29 +++++++ 9 files changed, 149 insertions(+), 39 deletions(-) create mode 100644 modules/end-user-guide/pages/reporting-vale-alerts.adoc rename modules/end-user-guide/pages/{getting-started-with-vale.adoc => using-vale-cli.adoc} (72%) create mode 100644 modules/end-user-guide/partials/proc_generating-extended-vale-alerts-reports.adoc create mode 100755 tools/report_vale_alerts.sh diff --git a/.vale/styles/RedHat/Headings.yml b/.vale/styles/RedHat/Headings.yml index d47114000..42c97926d 100644 --- a/.vale/styles/RedHat/Headings.yml +++ b/.vale/styles/RedHat/Headings.yml @@ -1,10 +1,11 @@ extends: capitalization message: "'%s' should use sentence-style capitalization." -link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N1030C' +link: "https://www.ibm.com/developerworks/library/styleguidelines/index.html#N1030C" level: suggestion scope: heading match: $sentence indicators: - - ':' + - ":" exceptions: - IBM + - Red Hat diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 74029982f..bb613d8fc 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -3,9 +3,10 @@ * xref:introduction.adoc[] * xref:redhat-style-for-vale.adoc[] * xref:glossary.adoc[] -* xref:getting-started-with-vale.adoc[] -* xref:understanding-vale-output.adoc[] +* xref:using-vale-cli.adoc[] * xref::using-vale-in-the-ide.adoc[] +* xref:reporting-vale-alerts.adoc[] +* xref:understanding-vale-output.adoc[] * xref:defining-a-vale-onboarding-strategy.adoc[] * xref:adding-vale-configuration-to-a-project.adoc[] * xref:creating-a-vocabulary-for-a-project.adoc[] diff --git a/modules/end-user-guide/pages/reporting-vale-alerts.adoc b/modules/end-user-guide/pages/reporting-vale-alerts.adoc new file mode 100644 index 000000000..5363f997c --- /dev/null +++ b/modules/end-user-guide/pages/reporting-vale-alerts.adoc @@ -0,0 +1,18 @@ +// Metadata for Antora +:navtitle: Vale reports +:keywords: reporting +// :page-aliases: +// End of metadata for Antora + +:parent-context-of-reporting-vale-alerts: {context} + +[id="generating-extended-vale-alerts-reports_{context}"] += Generating extended Vale alerts reports + +:context: generating-extended-vale-alerts-reports + +include::partial$proc_generating-extended-vale-alerts-reports.adoc[leveloffset=+1] + + +:context: {parent-context-of-generating-extended-vale-alerts-reports}] + diff --git a/modules/end-user-guide/pages/getting-started-with-vale.adoc b/modules/end-user-guide/pages/using-vale-cli.adoc similarity index 72% rename from modules/end-user-guide/pages/getting-started-with-vale.adoc rename to modules/end-user-guide/pages/using-vale-cli.adoc index 7cd632a99..210598490 100644 --- a/modules/end-user-guide/pages/getting-started-with-vale.adoc +++ b/modules/end-user-guide/pages/using-vale-cli.adoc @@ -1,13 +1,13 @@ // Metadata for Antora -:navtitle: Getting started +:navtitle: Vale CLI :keywords: vale -// :page-aliases: +:page-aliases: getting-started-with-vale // End of metadata for Antora :parent-context-of-assembly_getting-started-with-vale: {context} -[id="assembly_getting-started-with-vale_{context}"] -= Getting started with vale +[id="assembly_using-vale-cli_{context}"] += Using Vale CLI :context: assembly_getting-started-with-vale diff --git a/modules/end-user-guide/partials/proc_generating-extended-vale-alerts-reports.adoc b/modules/end-user-guide/partials/proc_generating-extended-vale-alerts-reports.adoc new file mode 100644 index 000000000..37d19412b --- /dev/null +++ b/modules/end-user-guide/partials/proc_generating-extended-vale-alerts-reports.adoc @@ -0,0 +1,40 @@ +:_module-type: PROCEDURE + +[id="proc_generating-extended-vale-alerts-reports_{context}"] += Generating extended Vale alerts reports + +Consider generating extended Vale alerts reports about a Git repository to: + +* Measure language compliance in a repository +* Gather data before xref:defining-a-vale-onboarding-strategy.adoc[] + +These reports use the Vale report in JSON format and additional information such as the word count. + +.Prerequisites + +* The `vale` tool is installed and configured. See xref:getting-started-with-vale.adoc[]. +* The `jq` tool is installed. See link:https://stedolan.github.io/jq/download/[Downloading `jq`]. + +.Procedure + + +. Generate vale alerts reports for __: ++ +[subs="+quotes,+attributes"] +---- +$ ./tools/report_vale_alerts.sh __ +---- + +. The script creates following files for each Git repository found at __: ++ +`vale-report__-list.log`:: List of AsciiDoc files considered for the report. +`vale-report__-wordcount.log`:: Word count for all files in the file list. Use this information to compare the number of alerts between repositories. +`vale-report__.json`:: Vale report in JSON format. Use the `jq` tool to query the results. +`vale-report__.severity`:: Breakdown of alerts by severity. +`vale-report__.rules`:: Breakdown of alerts by rules. + +.Additional resources + +* xref:understanding-vale-output.adoc[] +* xref:defining-a-vale-onboarding-strategy.adoc[] + diff --git a/modules/end-user-guide/partials/proc_using-vale-in-the-ide.adoc b/modules/end-user-guide/partials/proc_using-vale-in-the-ide.adoc index 635e6311c..877eb038c 100644 --- a/modules/end-user-guide/partials/proc_using-vale-in-the-ide.adoc +++ b/modules/end-user-guide/partials/proc_using-vale-in-the-ide.adoc @@ -11,7 +11,6 @@ Consider using Vale in your IDE when: .Prerequisites * Vale CLI is installed and configured. See xref:getting-started-with-vale.adoc[]. - * link:https://code.visualstudio.com/docs/setup/setup-overview[Visual Studio Code] is installed. .Procedure diff --git a/modules/end-user-guide/partials/proc_using-vale-on-a-local-environment.adoc b/modules/end-user-guide/partials/proc_using-vale-on-a-local-environment.adoc index 923da71c8..99db543e7 100644 --- a/modules/end-user-guide/partials/proc_using-vale-on-a-local-environment.adoc +++ b/modules/end-user-guide/partials/proc_using-vale-on-a-local-environment.adoc @@ -1,10 +1,10 @@ :_module-type: PROCEDURE -[id="proc_using-vale-on-a-local-environment_{context}"] -= Using vale on a local environment +[id="proc_using-vale-cli-on-a-local-environment_{context}"] += Using `vale` CLI on a local environment [role="_abstract"] -To use vale on any project in your local environment without further configuration in the projects, install the Vale CLI and register the *{repository-name}* vale configuration as the default. +To use `vale` CLI on any project in your local environment without further configuration in the projects, install the Vale CLI and register the *{repository-name}* vale configuration as the default. .Prerequisites diff --git a/modules/end-user-guide/partials/ref_defining-a-vale-onboarding-strategy.adoc b/modules/end-user-guide/partials/ref_defining-a-vale-onboarding-strategy.adoc index 12b8fd668..01dfc4c56 100644 --- a/modules/end-user-guide/partials/ref_defining-a-vale-onboarding-strategy.adoc +++ b/modules/end-user-guide/partials/ref_defining-a-vale-onboarding-strategy.adoc @@ -9,56 +9,78 @@ Embracing a linter in a project is a long journey. The full vale report can be d * The styles are not perfect or complete. * Assess the maturity of the project -== Decrease the number of alerts without changing the configuration file +.Prerequisites + +* xref:reporting-vale-alerts.adoc[] +* xref:understanding-vale-output.adoc[] -Consider these techniques to decrease the number of alerts: +== Assess the project maturity -* Display only *errors*. Don't display *warnings* and *suggestions*. -+ ----- -$ vale --minAlertLevel=error . ----- +Zero vale errors:: +The project is compliant with the `RedHat` style. Consider integration with a continuous integration service using the defaults from the `{repository-name}` repository. -* Display only *errors* and *warnings*. Don't display *suggestions*. +* xref:using-vale-github-action.adoc[] +* xref:using-vale-with-a-continuous-integration-service.adoc[] + +Under 100 Vale errors:: +The project is almost compliant with the `RedHat` style. Consider integration with a continuous integration service using the defaults from the `{repository-name}` repository. Consider massively fixing the few errors. + +Over 100 Vale errors:: +The project is big or poorly compliant with the `RedHat` style. Consider further investigation to understand the issue. + +== Fix the alerts + +* Run campaigns focused on one target such as: fix all errors, fix all occurrences of a given rule. + +* Disable a rule that is irrelevant in the file context. See: link:https://docs.errata.ai/vale/scoping[Vale - Scoping] + ---- -$ vale --minAlertLevel=warning . +pass:[] + +The Spelling rule is ignored for this line. + +pass:[] + +The Spelling rule is active for this line. + ---- -* Disable *rules* in a specific `.vale.ini` configuration. See link:https://docs.errata.ai/vale/config[Vale documentation - configuration]. +== Display less alerts without changing the configuration file + + +* Display only *errors*. Don't display *warnings* and *suggestions*. + ---- -Vale.Repetition = NO +$ vale --minAlertLevel=error . ---- -* Alter *rules* severity in a specific `.vale.ini` configuration. See link:https://docs.errata.ai/vale/config[Vale documentation - configuration]. +* Display only *errors* and *warnings*. Don't display *suggestions*. + ---- -RedHat.Annotations = suggestion -RedHat.Slash = warning -RedHat.Usage = suggestion +$ vale --minAlertLevel=warning . ---- -* Consider disabling a rule on the spot. See: link:https://docs.errata.ai/vale/scoping[Vale - Scoping] -+ ----- -pass:[] -The Spelling rule is ignored for this line. +== Contributing to the _{repository-name}_ repository -pass:[] +* xref:contributor-guide:extending-the-spelling-rule.adoc[] -The Spelling rule is active for this line. +* xref:contributor-guide:extending-the-redhat-style.adoc[] ----- +== Decrease the number of alerts requesting xref:adding-vale-configuration-to-a-project.adoc[] -* Consider xref:creating-a-vocabulary-for-a-project.adoc[]. +* xref:creating-a-vocabulary-for-a-project.adoc[] -* Consider xref:contributor-guide:extending-the-spelling-rule.adoc[]. +* Altering *rules* severity or disabling *rules* for the project. See xref:adding-vale-configuration-to-a-project.adoc[] and link:https://docs.errata.ai/vale/config[Vale documentation - configuration]. ++ +---- +RedHat.Annotations = NO +RedHat.Slash = warning +RedHat.Usage = suggestion +---- -* Consider xref:contributor-guide:extending-the-redhat-style.adoc[]. +* Creating an additional style for the project. See xref:adding-vale-configuration-to-a-project.adoc[] -* Consider creating an additional style for the project. [role="_additional-resources"] .Additional resources diff --git a/tools/report_vale_alerts.sh b/tools/report_vale_alerts.sh new file mode 100755 index 000000000..495fe94a8 --- /dev/null +++ b/tools/report_vale_alerts.sh @@ -0,0 +1,29 @@ +#!/bin/sh +# +# Copyright (c) 2021 Red Hat, Inc. +# This program and the accompanying materials are made +# available under the terms of the Eclipse Public License 2.0 +# which is available at https://www.eclipse.org/legal/epl-2.0/ +# +# SPDX-License-Identifier: EPL-2.0 +# +# Loop on each git repository found on location given as argument, or current directory +find "${1:-.}" -name .git -print | sed 's@/.git@@' | sort | uniq | while read directory; +do + echo "Generating report on $directory" + # Provide a full list of files to report on + # Ignore files containing a space + FILE_LIST=$(find "${directory}" -type f -name '*.adoc' -print | sed '/ /d'| sort | uniq) + REPORT_BASENAME=vale-report-$(basename "${directory}") + # Create file list + echo "$FILE_LIST" > "${REPORT_BASENAME}-list.log" + # Count words in the corpus + # shellcheck disable=SC2002,SC2086 + cat $FILE_LIST | wc -w > "${REPORT_BASENAME}-wordcount.log" + # Create Vale report + # shellcheck disable=SC2086 + vale --output=JSON --no-exit $FILE_LIST > "$REPORT_BASENAME.json" + # A minimal analyze + jq .[][].Severity "$REPORT_BASENAME.json" | sort | uniq -c | sort -nr > "$REPORT_BASENAME.severity" + jq .[][].Check "$REPORT_BASENAME.json" | sort | uniq -c | sort -nr > "$REPORT_BASENAME.rules" +done