Confusing vale output from Fluff.yml

[holly-cummins]

I tried to fix this, but couldn't figure out the best solution. That may be why we have the problem!

The Fluff.yml vale rule is extending substitution, but it's not actually a substitution rule - the things in the swap list aren't suggested before-and-after, they're problematic tokens and then explanations of what a user might want to do.

extends: substitution
message: "Depending on the context, consider using '%s' rather than '%s'."
swap:
  in order to: "Be concise: use 'to' rather than"
  needs? to: "Rewrite the sentence, or use 'must', instead of"
  note that: "Be concise: rewrite the sentence to not use"
  recommend: "using more direct instructions"
  respectively: "Rewrite the sentence to be more precise, instead of using"

Because of this, the messages for this rule come out as nonsense. For example,

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Be concise: rewrite the sentence to not use' rather than 'note that'.

The raw message makes a bit more sense, but it's still pretty confusing:

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Be concise: rewrite the sentence to not use' rather than 'note that'.", "location": {"path": "docs/src/main/asciidoc/extension-maturity-model.adoc", "range": {"start": {"line": 25, "column": 6}}}, "severity": "INFO"}

One possible fix is to split the Fluff.yml rule into a whole bunch of individual existence rules. If we wanted to have some grouping, we could make a fluff super-rule and extend it.

Alternatively, the message could be written so that the after was just a sentence on its own, but that's a bit of an abuse of the swap data. But it would be a faster fix, and keep all of the rules grouped in one file.

What do you think, @michelle-purcell and @ebullient?

[quarkus-bot[bot]]

/cc @MichalMaler (documentation), @ebullient (documentation), @inoxx03 (documentation), @michelle-purcell (documentation), @rolfedh (documentation), @sheilamjones (documentation), @sunayna15 (documentation)

[rolfedh]

FYI: Earlier this morning, I discussed with Michelle and created Managing Vale files for the Quarkus engineering team: A brief information sheet outlining our collaborative process with the Quarkus engineering team for managing Vale files. This document details our approach to customizing and updating Vale rules to meet the specific needs of Quarkus while aligning with Red Hat standards. Feedback and edits are welcome!