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 VISION.md #2704

Merged
merged 3 commits into from Jul 10, 2017

Conversation

4 participants
@jeddy3
Member

jeddy3 commented Jul 1, 2017

Ref: #2259 (comment)

I’ve been mulling this over for a while now. More so since prettier introduced support for CSS and CSS-like languages. This PR is part of a wider effort to help developers understand the benefits of each tool.

The VISION.md document touches on, what I believe to be, the recurring things from the issue tracker. I’ve tried to build on top of the original goals of the project (completeness, extensibility, consistency etc), while taking into account the changes to those goals and the new goals that have emerged over the last two years (performance, support for non-standard syntax etc). I’ve also tried to address some of the confusion around what are the differences/similarities between stylelint and pretty printers.

I’ve updated the list of rules so that they are first grouped by the three categories listed in the VISION.md:

  • Possible errors
  • Limit language features
  • Stylistic issues

I believe doing so:

  1. Highlights the unique linting strengths of stylelint i.e. the 26 error catching rules and the 48 limiting rules.
  2. Makes it easier for users who wish to use stylelint in conjunction with a pretty printer like prettier.

Additionally, I’ve created stylelint-config-recommended, which turns on just the error catching rules. Named for parity with eslint’s “recommended” config, which does a similar thing. Users of prettier would use this config (adding any additional limiting rules they need, while avoiding the stylistic rules).

I anticipate stylelint-config-standard will extend stylelint-config-recommended, and apply its current set of stylistic rules.

The final step is to update the stylelint documentation to reference both these shared configs, and to explain what their use cases are.

Closes #2532
Closes #2418

Add VISION.md
Closes #2532
Closes #2418
- A machine algorithmically pretty prints the code (usually based on a maximum line length).
- A human initially formats the code, and a machine fixes-up/warns-about any mistakes.
The former is handled by pretty printers, like [prettier](https://github.com/prettier/prettier), whereas the latter is catered for by the built-in stylistic rules.

This comment has been minimized.

@davidtheclark

davidtheclark Jul 1, 2017

Contributor

I think this gives a little too much credit to Prettier. Prettier's lack of configurability is the reason that stylelint is venturing into the --fix arena, right? To provide a more comprehensively configurable autofixer? I think it might be worth highlighting the difference between vision for these two types of autofixing. In fact, since I'm sure readers of this document will be very curious about this, I wonder if autofixing warrants a section of its own, to describe the goals particular to that (esp. differences from Prettier)?

This comment has been minimized.

@jeddy3

jeddy3 Jul 1, 2017

Member

@davidtheclark Thanks for the feedback!

Prettier's lack of configurability is the reason that stylelint is venturing into the --fix arena, right?

Yep, that is one of the reasons. The other is fixing things that prettier is unlikely to. I've tried (my brain has somewhat gone to mush) to address both in the changes I've just made :)

@davidtheclark

This comment has been minimized.

Contributor

davidtheclark commented Jul 1, 2017

Fantastic work, @jeddy3!

@ntwb

This comment has been minimized.

Member

ntwb commented Jul 2, 2017

Love it @jeddy3 💯

Myself, I've not yet grok'd all the prettier things and I've a question:

Can use both Stylistic rules and Prettier together?

For example, if I add the stylelint-ordering plugin and can I also use Prettier and will Prettier then print all the CSS in the order I defined in my config?

@jeddy3

This comment has been minimized.

Member

jeddy3 commented Jul 2, 2017

Can use both Stylistic rules and Prettier together?

Yes, they're just tools in a chain. I anticipate users will run stylelint first (with the stylelint-order plugin) to shift around the order of the things (declarations, rules etc) within blocks. Prettier would run second to format the whitespace and other things.

Some users might choose to do it the other way around too.

@hudochenkov

Fascinating work! Very good explanation. And categorizing rules is awesome and will help new (and experienced) users find right rules for their needs.

I left few notes.

VISION.md Outdated
Provide a fast tool, and the means to test and improve performance, including:
- [Benchmarking](docs/developer-guide/rules.md#improving-the-performance-of-a-new-or-an-existing-rule)of an individual rule's performance.

This comment has been minimized.

@hudochenkov

hudochenkov Jul 3, 2017

Member

Space after a link is missing.

This comment has been minimized.

@jeddy3

jeddy3 Jul 4, 2017

Member

Will fix.

VISION.md Outdated
Provide a robust tool with a [comprehensive test suite](docs/developer-guide/rules.md#write-tests), including:
- High coverage, currently over 95%.
- A wide range of fixtures for rules, currently over 40000.

This comment has been minimized.

@hudochenkov

hudochenkov Jul 3, 2017

Member

Where this number came from? Jest is reporting only 12 805 tests on v8 branch.

This comment has been minimized.

@jeddy3

jeddy3 Jul 4, 2017

Member

Oops, I picked a number out of the air as a placeholder until I checked the actual figure. Which I forgot to do :)

Will fix.

@hudochenkov

This comment has been minimized.

Member

hudochenkov commented Jul 3, 2017

P. S. I won't have much time for stylelint work this and the next week, because I just moved to the Netherlands and have lots of things to do beside open-source :)

@jeddy3 jeddy3 merged commit 2aa33a7 into v8 Jul 10, 2017

3 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
coverage/coveralls Coverage remained the same at 95.676%
Details

@jeddy3 jeddy3 deleted the vision-md branch Jul 10, 2017

jeddy3 added a commit that referenced this pull request Jul 14, 2017

8.0.0 (#2735)
* Add stylelint semantic versioning policy

* Fix whitespace and empty lines

* Add changelog entry

* Remove stylelint-config=standard reference

* Tweak major release optional options verbiage

* Update changelog

* Props ESLint

* Fix false negatives with ignore: ["descendant"] in selector-no-type (#2200)

* Update CHANGELOG.md

* Fix handling of shared-line comments (#2262)

* Fix handling of shared-line comments

Introduces a number of utilities and adjusts the following rules:
at-rule-empty-line-before, custom-property-empty-line-before,
declaration-empty-line-before, rule-nested-empty-line-before,
rule-non-nested-empty-line-before

Closes #2237; closes #2239; closes #2240.

* Fixes based on feedback

* Use getPreviousNonSharedLineCommentNode more

* Use more new helpers in comment-empty-line-before

* Add ignore: ["child"] option to selector-no-type (#2217)

* Add ignore: ["child"] option to selector-no-type

* Correct logic for ignore: ["child"] option

* Include line and column in reject tests with multiple type selectors

* Update CHANGELOG.md

* Report every selector resolved selector in selector-max-compound-selectors (#2350)

* Update CHANGELOG.md

* Add new shorthand data (#2354)

* Add new shorthand data

* Add mask shorthand

* Use defined list of properties in shorthand-property-no-redundant-values

* Improve declaration-block-no-shorthand-property-overrides speed a little bit

* Check prefixed properties agains prefixed properties in declaration-block-no-shorthand-property-overrides

* Improve declaration-block-no-redundant-longhand-properties speed a little bit

* Ignore prefixes case in declaration-block-no-shorthand-property-overrides

* Check prefixed properties agains prefixed properties in declaration-block-no-redundant-longhand-properties

* Add `grid-gap` to shorthand-property-no-redundant-values

* Explain properties set for shorthand-property-no-redundant-values

* Revert unnecessary changes

* Add “mask” to declaration-block-no-redundant-longhand-properties readme

* Update CHANGELOG.md

* Update changelog

* Remove deprecated rules (#2422)

* Remove deprecated rules

* Include `rule-empty-line-before` in system tests

* *-empty-line-before rules consider line as empty if it contains whitespace only (#2440)

* Update CHANGELOG.md

* Remove deprecated options (#2433)

* Update CHANGELOG.md

* report-needless-disables now exits with non-zero code (#2341)

* Update CHANGELOG.md

* Remove leftover files (#2442)

* Remove leftover file

* One more

* And one more

* Ignoring improvements (#2464)

* WIP ignoring improvements

* Remove standaloneIgnored property of result

* Add disableDefaultIgnores

* Add documentation tweaks

* Add parseStylelintIgnore tests

* Non-absolutized ignore file paths

* Restire gitignore syntax

* Remove parseStylelintIgnore

* Update CHANGELOG.md

* Check all linear-gradients in a value list (#2496)

Closes #2481

* Update CHANGELOG.md

* Update CHANGELOG.md

* Respect line case for `ignorePattern` (#2683)

Closes #2647

* Update CHANGELOG.md

* Update decls

* Fix remark warning

* Update snapshots

* Add missing message to reject test

* Fix tests for *-empty-line-before rules (#2688)

* Fix tests for *-empty-line-before rules

* Test addition and tweak

* Update to PostCSS@6 (#2561)

* Update to PostCSS@6

* Fix PostCSS@6 closing-brace test (#2689)

* Account for PostCSS@6's support for at-apply

* Remove only

* Fix postcssPlugin tests (#2690)

* Fix defaultSeverity.test.js test

* Fix ignoreDisables test

* Check ownSemiColon

* Fixed: remove hacks related to custom property set.

* Remove deprecated rules (#2693)

Closes #2521

* Update CHANGELOG.md

* Update CHANGELOG.md

* Add VISION.md (#2704)

* Add releases.md (#2705)

* Add releases.md

Closes #2700

* Add dry-release step

* Use HTTPS for links

* Change ignore options for selector-max-type (#2701)

* Fix false negatives with ignore descendant

* Add ignore child

Closes #2699

* Update CHANGELOG.md

* Update README.md to account for VISION.md (#2727)

* Update README.md to account for VISION.md

* Fix lint warnings in CHANGELOG

* Update postcss-less to 1.0 (#2702)

* Update postcss-less to 1.0.2

* Update isStandardSyntaxRule for postcss-less 1.0

* Pass custom postcss stringifier when creating result

* Correct no-extra-semicolons Less test position

* Ignore Less mixins in no-extra-semicolons

* Update postcss-less to 1.1.0

* Correct no-extra-semicolons Less test position again

* Utilize isStandardSyntaxRule when checking for Less rules in no-extra-semicolons

* Case sensitive white/blacklists and ignore* options (#2709)

Closes #2660

* Update CHANGELOG.md

* docs: Add "New Release Issue Template" to releases.md (#2728)

* Exit with non-zero code on postcss warnings (#2713)

* Enhancement: exit with non zero code on postcss warnings.

* Account for parseErrors in stringformatqer

* Guard against no parseErrors

* Update CHANGELOG.md

* Refactor: simplify ignore logic. (#2732)

* Update changelog

* Bump 8.0.0 changes to top

* Correctly place changelog items

* Add introduction

* Add codefence for website

* Use relative path

* Include VISION in package for website

* Add link to VISION doc for website

* Changelog amends

* Update releases.md (#2738)

* Update eslint and config (#2737)

* Order requires

* Use eqeqeq eslint rule

* Update eslint

* Disable no-useless-escape just for this repo

* Enable no-useless-escape rule

* Use tilde

* Fix enable comment

* Add reject test for unescaped regex
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment