Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add deprecated rule warnings #6561

Merged
merged 6 commits into from
Jan 26, 2023
Merged

Add deprecated rule warnings #6561

merged 6 commits into from
Jan 26, 2023

Conversation

ybiquitous
Copy link
Member

Which issue, if any, is this issue related to?

Ref: #6409

Is there anything in the PR that needs further explanation?

To notify deprecation and make the migration easier.
Such warnings are added to a linting result and reporting output.

For example of a report:

$ cd scripts
$ ../bin/stylelint.js visual.css --config=visual-config.json

Deprecation Warning: The "string-quotes" rule is deprecated and will be removed in the next major release.
Deprecation Warning: The "unit-case" rule is deprecated and will be removed in the next major release.

visual.css
 1:9   ✖  Expected "url("foo.css")" to be ""foo.css""       import-notation
 1:13  ✖  Expected single quotes                            string-quotes
 4:9   ✖  Unexpected invalid hex color "#4f"                color-no-invalid-hex
 6:1   ✖  Expected ".foo.bar" to have no more than 1 class  selector-max-class
 7:10  ✖  Unexpected unit "px"                              unit-disallowed-list
 8:3   ⚠  Expected custom property name to be kebab-case    custom-property-pattern

6 problems (5 errors, 1 warning)

To notify deprecation and make the migration easier.
Such warnings are added to a linting result and reporting output.

For example of a report:

```console
$ cd scripts
$ ../bin/stylelint.js visual.css --config=visual-config.json

Deprecation Warning: The "string-quotes" rule is deprecated and will be removed in the next major release.
Deprecation Warning: The "unit-case" rule is deprecated and will be removed in the next major release.

visual.css
 1:9   ✖  Expected "url("foo.css")" to be ""foo.css""       import-notation
 1:13  ✖  Expected single quotes                            string-quotes
 4:9   ✖  Unexpected invalid hex color "#4f"                color-no-invalid-hex
 6:1   ✖  Expected ".foo.bar" to have no more than 1 class  selector-max-class
 7:10  ✖  Unexpected unit "px"                              unit-disallowed-list
 8:3   ⚠  Expected custom property name to be kebab-case    custom-property-pattern

6 problems (5 errors, 1 warning)
```
@changeset-bot
Copy link

changeset-bot bot commented Jan 5, 2023

🦋 Changeset detected

Latest commit: 54a2305

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

This PR includes changesets to release 1 package
Name Type
stylelint Minor

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

@ybiquitous ybiquitous marked this pull request as ready for review January 5, 2023 16:38
Copy link
Member

@jeddy3 jeddy3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ybiquitous I've made one minor suggestion, otherwise LGTM.

*/
function warnDeprecatedRule(result, ruleName) {
result.warn(
`The "${ruleName}" rule is deprecated and will be removed in the next major release.`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`The "${ruleName}" rule is deprecated and will be removed in the next major release.`,
`The "${ruleName}" rule is deprecated.`,

Let's keep it succinct in the terminal to avoid a wall of text.

Copy link
Member

@Mouvedia Mouvedia Jan 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about having just one sentence with a list of the matched rules instead of multiple sentences?
e.g. The "string-quotes", "unit-case" and "foo-bar" rules are deprecated and will be removed in the next major release.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the advice. I've simplified warning messages via ff83ba8. Here is a screenshot:

image

I keep multiple sentences because each message may have a reference, and it's hard to include reference(s) in one sentence. See the code below:

if (reference) {
line += dim(` See: ${underline(reference)}`);
}

Instead, I've avoided repeated "Deprecation Warning" messages in each line and appended a " - " prefix to each line.

What about this change?

Copy link
Member

@Mouvedia Mouvedia Jan 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[suggestion]

Let's take stylelint config standard as the baseline.
Let's say a user resets about 19% of the deprecated rules; that clocks at around 12 lines out of potentially 64.
In that scenario I would prefer a counter and the usage of or etc. for more than 3.
e.g.

`${count} deprecation warnings for rules ${rules[0]},  ${rules[1]}, ${rules[2]}, etc.`

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about this change?

SGTM, thank you.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Mouvedia I understand your concern. But, if reference is specified with a rule deprecation, how should we display it with or etc.? I believe we need to consider also plugin rules, not only the built-in ones.

Copy link
Member

@Mouvedia Mouvedia Jan 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, as long as we have an ENV variable—or something similar—that hides those warnings it should be OK.
@ybiquitous Does the --quiet option hide these warnings?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does the --quiet option hide these warnings?

I'm afraid the answer is no because these warnings are not related to a warning severity produced by lint rules. We currently don't have a way to suppress this kind of warning, except for using a custom formatter.

lib/formatters/stringFormatter.js Outdated Show resolved Hide resolved
@ybiquitous
Copy link
Member Author

Maybe off-topic, but I found the following description in our developer guide:

1. Point the `stylelintReference` link to the specific version of the rule README on the GitHub website, so that it is always accessible.

Indeed, the stylelintReference property seems not to be used:

$ git grep -w 'stylelintReference' lib/
lib/createPartialStylelintResult.js:32:                reference: deprecationMessage.stylelintReference,

Should we follow the guideline still? If doing that, this PR change would show a large amount of text for users.

Copy link
Member

@jeddy3 jeddy3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thank you!

Should we follow the guideline still?

Narh, as we're making these deprecations as part of a major release. People will find the general migration guide. This advice was for when we'd deprecate the occasional rule in a minor release, and we'd need to direct people to migration steps in each rule's README.

@ollie-iterators
Copy link

ollie-iterators commented Jan 17, 2023

When will this be getting merged? Also, once this PR gets merged, will it cause #6573 to be able to be merged so that stylelint can be updated to version 15.0.0?

@jeddy3
Copy link
Member

jeddy3 commented Jan 19, 2023

When will this be getting merged?

The original author usually merges once a pull request has one approval. So, it'll be merged whenever @ybiquitous has time. We're all volunteers so things happen when they happen.

Also, once this PR gets merged, will it cause #6573 to be able to be merged so that stylelint can be updated to version 15.0.0?

Yes, that's likely. I'll update #6409 to bring things together.

@jeddy3 jeddy3 mentioned this pull request Jan 19, 2023
@ybiquitous
Copy link
Member Author

Because we will deprecate many rules in v15.0.0, some may see many deprecation warnings and feel annoyed. But I believe showing warnings should be better than showing nothing.

Also, if people update stylelint and stylelint-config-{recommended,standard} at the same time, they will not see the warnings, since the configs will remove deprecation rules.

We can consider adding an option to turn off deprecation warnings if people need it.

If there is no other feedback, I will merge this PR within a few days.

@jeddy3
Copy link
Member

jeddy3 commented Jan 25, 2023

Also, if people update stylelint and stylelint-config-{recommended,standard} at the same time, they will not see the warnings, since the configs will remove deprecation rules.

Yep, exactly.

If there is no other feedback, I will merge this PR within a few days.

Merging SGTM.

@Mouvedia
Copy link
Member

We can consider adding an option to turn off deprecation warnings if people need it.

I will for the 15.1.0 version.

@ybiquitous
Copy link
Member Author

I will for the 15.1.0 version.

Let's open an issue when it becomes necessary.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

4 participants