Skip to content

Commit

Permalink
docs: generating reports, onboarding strategy
Browse files Browse the repository at this point in the history
  • Loading branch information
themr0c committed Oct 26, 2021
1 parent d0b81de commit 5d346db
Show file tree
Hide file tree
Showing 9 changed files with 149 additions and 39 deletions.
5 changes: 3 additions & 2 deletions .vale/styles/RedHat/Headings.yml
Original file line number Diff line number Diff line change
@@ -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
5 changes: 3 additions & 2 deletions modules/end-user-guide/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down
18 changes: 18 additions & 0 deletions modules/end-user-guide/pages/reporting-vale-alerts.adoc
Original file line number Diff line number Diff line change
@@ -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}]

Original file line number Diff line number Diff line change
@@ -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

Expand Down
Original file line number Diff line number Diff line change
@@ -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 _<location>_:
+
[subs="+quotes,+attributes"]
----
$ ./tools/report_vale_alerts.sh _<location>_
----

. The script creates following files for each Git repository found at _<location>_:
+
`vale-report_<repository>_-list.log`:: List of AsciiDoc files considered for the report.
`vale-report_<repository>_-wordcount.log`:: Word count for all files in the file list. Use this information to compare the number of alerts between repositories.
`vale-report_<repository>_.json`:: Vale report in JSON format. Use the `jq` tool to query the results.
`vale-report_<repository>_.severity`:: Breakdown of alerts by severity.
`vale-report_<repository>_.rules`:: Breakdown of alerts by rules.

.Additional resources

* xref:understanding-vale-output.adoc[]
* xref:defining-a-vale-onboarding-strategy.adoc[]

Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:[<!-- vale RedHat.Spelling = NO -->]
The Spelling rule is ignored for this line.
pass:[<!-- vale RedHat.Spelling = YES -->]
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:[<!-- vale RedHat.Spelling = NO -->]

The Spelling rule is ignored for this line.
== Contributing to the _{repository-name}_ repository

pass:[<!-- vale RedHat.Spelling = YES -->]
* 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
Expand Down
29 changes: 29 additions & 0 deletions tools/report_vale_alerts.sh
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 5d346db

Please sign in to comment.