Acrolinx creates comments on Git hosting providers and sets the status of a commit.
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.
Note
In the future, github
will be replaced with githost
. For now, please continue to use the string github
.
Example:
:template-header "## Acrolinx Report" :template-change "* Result for ${github/filename} ${acrolinx/scorecard}" :template-footer "\n----\n"
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.
Note
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.
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}
.
You can use these variables in :template-change:
.
Note
If you've enabled Targets and are using Targets variables, you need to enable :acrolinx-new-api
and :use-gh-statuses
.
Variable Prefix |
Example |
Description |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Link to checked file version in GFM. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Processing status covering download and check. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Filename, including subdirectory, in the changeset on your Git hosting provider, relative to the root of the repository. NoteYou can use this variable prefix in both GitHub and Azure DevOps Git. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Number of words checked. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Number of sentences checked. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Acrolinx Score |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Status color according to server settings (green, yellow, red). |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
Link to HTML scorecard. Isn’t authenticated and may require sign-in to server. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Note
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.
You can use these variables in :template-footer
and :template-header
:.
Variable |
Example |
Description |
---|---|---|
|
|
Link to Content Analysis Dashboard. The Content Analysis dashboard URL won’t be displayed, if Acrolinx couldn't check all files in the pull request event. |
|
|
Number of documents successfully checked. |
|
|
The number of relevant documents to be checked after Acrolinx filters relevant changes and limits to a maximum number of allowed changes. |
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.
Acrolinx uses these statuses as follows:
-
success - Everything went fine. Acrolinx could check the files and they all met the defined criteria.
Note
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
tofalse
. -
failure - Acrolinx could check all files, but at least one of them didn't meet the defined criteria.
-
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.
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.
Note
Note that if you filter events by sender or event type, Acrolinx won’t update the status.
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.
If you've enabled Targets, the criteria are:
-
:qualityscore
(Acrolinx Score, based on the Acrolinx scoring strategy configuredfor your Acrolinx Platform) -
:average
(average of all goal scores) -
:minimum
(lowest goal score) -
:tone
-
:inclusive
-
:words_and_phrases
-
:correctness
-
:consistency
-
:scannability
-
:clarity
If you use Guidance Profiles, the criteria are:
-
:qualityscore
(Acrolinx Score, based on the Acrolinx scoring strategy configured for your Acrolinx Platform) -
:average
(average of all category scores) -
:minimum
(lowest category score) -
:readability
-
:terminology
-
:grammar
-
:style
-
:spelling
-
:informality
-
:terminology_valid
-
:min-score
(lowest category score from old Acrolinx API)
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.
Then your configuration would look like this:
{:targets {:scores {:grammar 80 :terminology 90} :counts {:spelling 0 }}}
To allow each repository to focus on different criteria, you'll set this in the repository-specific configuration.
Note
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.
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."
Acrolinx offers one extra parameter that makes it easier to set a useful target:
-
:total
- The sum of all issue counts. You can use this in:counts
as a target.