🦋 Changeset detected

Latest commit: 0a199d6

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@jhae-de Thanks for the pull request.

I can't remember if this was an intentional design decision, as we added the message property a few years ago.

We can either:

• automate adding the rule name via this PR
• update our docs to say the rule name must be added manually if the users want it, and fix the custom messages rule in our shared configs so they end with the rule name

It seems the former leads to automated consistency, and the latter to choice.

Let's see if any other maintainers have an opinion.

Context: this is for the text property of the result object. Our string formatter removes the rule name from the message so that it can be placed in another column:

@jeddy3 Thanks for your feedback.

I had also thought about which of the two approaches would be better beforehand. The decisive factor for me in the end was that the messages defined in the built-in rules are also automatically enriched with the rule names. Applying this to custom messages as well was the logical consequence for me.

I am curious to hear what others think about this.

@jhae-de Thank you for discovering and fixing the issue. I implemented the custom message feature, but this problem was out of my mind, sorry.

First, let me show where the (<rule-name>) text is constructed in a lint problem message. It's a public utility stylelint.utils.ruleMessages():

• stylelint/lib/utils/ruleMessages.mjs

  Lines 10 to 12 in b478202

  	newMessages[messageId] = `${messageText} (${ruleName})`;
  	} else {
  	newMessages[messageId] = (...args) => `${messageText(...args)} (${ruleName})`;

• stylelint/docs/developer-guide/plugins.md

  Line 245 in b478202

  ### `stylelint.utils.ruleMessages()`

Second, our default string formatter removes the (<rule-name>) text from a problem message here:

• stylelint/lib/formatters/stringFormatter.mjs

  Lines 182 to 186 in b478202

  	const ruleString = ` (${message.rule})`;
  	if (result.endsWith(ruleString)) {
  	result = result.slice(0, result.lastIndexOf(ruleString));
  	}

So, to achieve consistency for problem messages, we may need to choose either of the two options below:

1. Add (<rule-name>) to custom messages, too (like this PR does)
2. Remove (<rule-name>) from any messages (breaking)

If we choose option 1, there is a little possibility of breaking, but its impact should not be significant.

Instead, if we opt for option 2, it should be shipped in a major version.

Personally, I'm leaning towards option 2 because I think it's verbose to contain (<rule-name>) in a message. Let's see this example that the current Stylelint contains in the JS object:

{
  "rule": "block-no-empty",
  "text": "Unexpected empty block (block-no-empty)"
}

As shown above, our default string (also verbose) formatter removes this duplication before outputting it, like this:

✖  Unexpected empty block      block-no-empty

To make custom formatters easier to implement, should we separate (<rule-name>) from a message? Any thoughts?

@ybiquitous Thank you for your feedback and some context regarding the rule messages.

I hadn't actually thought about the option of removing the rule names from the messages altogether. At first, I didn't think the idea was so bad, as my main concern here was consistency.

However, I would like to point out the following:

1. The compact and unix formatters currently only output the rule messages. With these outputs, we would also lose the rule names here.
2. The rule names would also no longer be displayed in some IDEs. For example, PhpStorm only outputs the rule messages. To my knowledge, there is no way to configure Stylelint with custom options here, e.g., to customize the formatter. The output does not change even if I specify the formatter in the Stylelint configuration file itself.

Output in PhpStorm:

At least as far as point 2 is concerned, I always liked that the rule names were also displayed here. In this respect, I would personally find it regrettable if we were to remove the rule names from the messages in general.

@jhae-de Thanks for the feedback, too!

Regarding the compact and unix formatters, it would be easy to keep the message compatibility by explicitly adding (<rule-name>). 👌🏼

About some IDEs, I didn't have any ideas before your comment, such as PhpStorm. Thank you for the info. I think it'd be more flexible to construct messages if (<rule-name>) were removed, but some clients might expect that messages would still contain (<rule-name>) by default, as you mentioned.

I don't recall any requests for such flexibility having been submitted. Maybe, no requests.

So now, it seems reasonable to me to add (<rule-name>) to custom messages, as well. Probably, I guess that it won't be a breaking change. 👍🏼

@jeddy3 Any thoughts?

So now, it seems reasonable to me to add (<rule-name>) to custom messages, as well.

SGTM. In addition to IDEs like PhpStorm, the rulename is useful when Stylelint is used as a PostCSS plugin and postcss-reporter reports the warnings:

We now recommend using our built-in formatters via the CLI or Node.js API, but some people may still be using the PostCSS plugin.

This PR is packaged and the instant preview is available (0a199d6). View the demo website.

Install it locally:

npm i -D https://pkg.pr.new/stylelint@0a199d6

It looks to me as if this PR will be accepted. Is there anything else I need to do, such as generating the changeset?

@jhae-de Yes, please add a changelog, respecting the PR title, e.g.:

---
"stylelint": minor
---
Added: rule name to custom messages