[en] Check Results

[en] Acrolinx creates comments on Git hosting providers and sets the status of a commit.

[en] Comments

[en] Acrolinx creates comments to show the results of an Acrolinx check. This is based on a template system that allows the configuration of comments posted. The template system comes with the settings below. All template variables support the ENV, system setting, and repository configuration files. You won't see their default here.

Anmerkung

[en] In the future, github will be replaced with githost. For now, please continue to use the string github.

[en] Example:

:template-header  "## Acrolinx Report" 
:template-change 
  "* Result for ${github/filename} ${acrolinx/scorecard}" 
:template-footer  "\n----\n"

[en] Acrolinx posts comments to the pull request and head commit pages of the event that started the processing. The comments use a simple templating system that allows access to the Acrolinx results via variables. Configure templates using template-header, :template-change, and :template-footer in your configuration file.

Anmerkung

[en] Acrolinx sets the status of all comments it posts to Azure DevOps Git to "Unknown." That way, you can merge pull requests without having to manually change the status of the comments that include check summary information. This applies to the status of the comments themselves, not to the status of the Acrolinx quality gate.

[en] Variables in the Template

[en] The templates fall into two categories: one template per event (header, footer) and one template per document (change). For both, you can use different variables to gather different types of information. Reference all variables using the notation ${NAME_OF_VARIABLE}, for example ${github/filename}.

[en] Variables for a Document

[en] You can use these variables in :template-change:.

Anmerkung

[en] If you've enabled Targets and are using Targets variables, you need to enable :acrolinx-new-api and :use-gh-statuses.

[en] Variable Prefix

[en] Example

[en] Description

[en] s/file

...

[en] Link to checked file version in GFM.

[en] s/status

...

[en] Processing status covering download and check.

[en] github/filename

[en] README.md

[en] Filename, including subdirectory, in the changeset on your Git hosting provider, relative to the root of the repository.

Anmerkung

[en] You can use this variable prefix in both GitHub and Azure DevOps Git.

[en] acrolinx/words

100

[en] Number of words checked.

[en] acrolinx/sentences

50

[en] Number of sentences checked.

[en] acrolinx/qualityscore

50

[en] Acrolinx Score

[en] acrolinx/qualitystatus

[en] red

[en] Status color according to server settings (green, yellow, red).

[en] acrolinx/scorecard

[en] http://...

[en] Link to HTML scorecard. Isn’t authenticated and may require sign-in to server.

[en] acrolinx/counts/...

[en] Guidance Profiles			[en] Targets
[en] Suffix	[en] Example	[en] Description	[en] Suffix	[en] Example	[en] Description
[en] `style` [en] `readability`	`1` `0`	[en] Count of style issues if checked. [en] Count of readability/clarity issues if checked	[en] `clarity`	`1`	[en] Number of clarity issues if checked.
[en] `style`	`1`	[en] Count of style issues if checked.	[en] `consistency`	`0`	[en] Count of consistency issues if checked.
[en] `grammar` [en] `spelling`	`0` `1`	[en] Count of grammar issues if checked. [en] Number of spelling issues if checked.	[en] `correctness`	`1`	[en] Count of correctness issues if checked.
[en] `informality`	`0`	[en] Count of informality/conversational tone issues if checked	[en] `tone`	`0`	[en] Number of tone issues if checked.
[en] `terminology_valid` [en] `terminology_deprecated` [en] `terminology_admitted`	`4` `5` `0`	[en] Count of valid terms if checked. [en] Number of deprecated terms if checked. [en] Number of admitted terms if checked.	[en] `words_and_phrases`	`0`	[en] Number of words and phrases issues if checked
			[en] `inclusive`	`0`	[en] Count of inclusive language issues if checked.
			[en] `scannability`	`0`	[en] Count of scannability issues if checked.
[en] `issues`	`7`	[en] Total number of issues considered errors.
[en] `total`	`11`	[en] Total number of issues.	[en] `total`	`2`	[en] Absolute issue count. This can't be combined with the other possible categories.

[en] acrolinx/scores/...

[en] Guidance Profiles			[en] Targets
[en] Suffix	[en] Example	[en] Description	[en] Suffix	[en] Example	[en] Description
[en] `min-score`	`37`	[en] Minimum score of all goal scores.	[en] `minimum`	`70`	[en] Minimum score of all goal scores.
[en] `style` [en] `readability`	`80` `90`	[en] Score by goal of same name. [en] Score by goal of same name.	[en] `clarity`	`90`	[en] Score for Clarity goal.
[en] `style`	`99`	[en] Score by goal of same name.	[en] `consistency`	`80`	[en] Score for Consistency goal.
[en] `grammar` [en] `spelling`	`80` `99`	[en] Score by goal of same name. [en] Score by goal of same name.	[en] `correctness`	`80`	[en] Score for Correctness goal.
[en] `informality`	`80`	[en] Score by goal of same name.	[en] `tone`	`80`	[en] Score for Tone goal.
[en] `terminology`	`44`	[en] Score by goal of same name.	[en] `words_and_phrases`	`80`	[en] Score for Words and Phrases goal.
			[en] `inclusive`	`70`	[en] Score for Inclusive Language goal.
			[en] `scannability`	`80`	[en] Score for Scannability goal.
			[en] `average`	`90`	[en] Average of all goal scores.
			[en] `qualityscore`	`90`	[en] Acrolinx Score, based on the scoring strategy configured for your Acrolinx Platform.

Anmerkung

[en] You might see different variables for issues and scores depending on the goals of your Acrolinx Platform. There can also be slight differences between the new Acrolinx API and the Classic API.

[en] Variables for an Event

[en] You can use these variables in :template-footer and :template-header:.

[en] Variable

[en] Example

[en] Description

[en] acrolinx/aggregdash

[en] http://...

[en] Link to Content Analysis Dashboard.

[en] The Content Analysis dashboard URL won’t be displayed, if Acrolinx couldn't check all files in the pull request event.

[en] acrolinx/nsuccess

10

[en] Number of documents successfully checked.

[en] acrolinx/ndocs

10

[en] The number of relevant documents to be checked after Acrolinx filters relevant changes and limits to a maximum number of allowed changes.

[en] Statuses - Acrolinx as a Quality Gateway

[en] You can use Acrolinx as a quality gateway for the content that you and your team create on your Git hosting provider. For this, we use the relevant Statuses API. The Statuses API lets you set a "success," "failure," or "error" status for a particular commit (and by extension for a pull request). This depends on a defined criteria.

[en] Acrolinx uses these statuses as follows:

[en] success - Everything went fine. Acrolinx could check the files and they all met the defined criteria.

Anmerkung

[en] Note that Acrolinx sets the status to "success" even when it didn't check any files. To toggle this behavior, set :gh-status-when-no-check to false.
[en] failure - Acrolinx could check all files, but at least one of them didn't meet the defined criteria.
[en] error - Something went wrong. This could be a network hiccup while downloading files, a Git hosting provider, or a syntax error in the file itself.

[en] Acrolinx can handle unspecific errors during a check in two different ways. By default, it sets the status to error. But you can set :gh-status-skip-errors to true. Then Acrolinx ignores all unprocessable files and continues with a full status check on the remaining files.

Anmerkung

[en] Note that if you filter events by sender or event type, Acrolinx won’t update the status.

[en] Defining Criteria

[en] Define the criteria that you want to meet with a special configuration setting. The available criteria include the strategy scores and category/goal scores from Acrolinx. They differ depending on whether you use Guidance Profile or have enabled Targets.

[en] Targets

[en] If you've enabled Targets, the criteria are:

[en] :qualityscore (Acrolinx Score, based on the Acrolinx scoring strategy configuredfor your Acrolinx Platform)
[en] :average (average of all goal scores)
[en] :minimum (lowest goal score)
[en] :tone
[en] :inclusive
[en] :words_and_phrases
[en] :correctness
[en] :consistency
[en] :scannability
[en] :clarity

[en] Guidance Profiles

[en] If you use Guidance Profiles, the criteria are:

[en] :qualityscore (Acrolinx Score, based on the Acrolinx scoring strategy configured for your Acrolinx Platform)
[en] :average (average of all category scores)
[en] :minimum (lowest category score)
[en] :readability
[en] :terminology
[en] :grammar
[en] :style
[en] :spelling
[en] :informality
[en] :terminology_valid
[en] :min-score (lowest category score from old Acrolinx API)

[en] Example

[en] Let's say that you want an Acrolinx Score of 90 for terminology, a score of 80 for grammar, and to have exactly 0 (zero) spelling issues.

[en] Then your configuration would look like this:

{:targets 
  {:scores {:grammar      80 
            :terminology  90} 
   :counts {:spelling  0 }}}

[en] To allow each repository to focus on different criteria, you'll set this in the repository-specific configuration.

Anmerkung

[en] Be aware that the repository-specific settings completely replace the global settings. You can't inherit the global settings and then just change some of them.

[en] Keep in mind that you’ll need to assign an exact number-based score. You can’t specify something like: "The grammar score must be above 80 and the spelling issues below 2 OR the total score must be higher than 90."

[en] Acrolinx offers one extra parameter that makes it easier to set a useful target:

[en] :total - The sum of all issue counts. You can use this in:counts as a target.

Wie können wir helfen?

Suche

[en] Comments

Anmerkung

Anmerkung

[en] Variables in the Template

[en] Variables for a Document

Anmerkung

Anmerkung

Anmerkung

[en] Variables for an Event

[en] Statuses - Acrolinx as a Quality Gateway

Anmerkung

Anmerkung

[en] Defining Criteria

[en] Targets

[en] Guidance Profiles

[en] Example

Anmerkung