docs: revamp Style Guide

[phanan]

trafficstars

As discussed, this is my attempt to revamp our Style Guide with inspirations taken from Dart. The list of changes is as follow:

• Instead of priorities ("essential," "strongly recommended" etc.) we use descriptive verbs: DO, DON'T, AVOID, PREFER, and CONSIDER for the guidelines
• As a side effect, each guideline's header (which is presented in the sidebar) is now a complete sentence, making it easier to skim through
• Since the headers are now much more descriptive, some of the texts have become redundant and removed
• The whole section to explain what each of the priority means is also removed understandably
• Since priorities are no longer a thing, the guidelines are now grouped by what they target, for example, "naming," "templating," "patterns & practice" etc. This, however, can use some suggestions from the team.

[phanan]

Preview available at https://deploy-preview-2839--vuejs.netlify.app/v2/style-guide/.

[NataliaTepluhina]

@phanan fair warning: as the PR is quite big, the review will take some time 😅

[phanan]

Totally understand. However, I’d strongly suggest looking at the deploy preview instead (or use it as the main ref), as the git diff makes little sense 😅

On Sun 20. Jun 2021 at 16:43 Natalia Tepluhina @.***> wrote:

@phanan https://github.com/phanan fair warning: as the PR is quite big, the review will take some time 😅

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/vuejs/vuejs.org/pull/2839#issuecomment-864565233, or unsubscribe https://github.com/notifications/unsubscribe-auth/AB5O3UVP2LVKZX5FA7CBX73TTX475ANCNFSM47AEAW4A .

[LinusBorg]

This would have an impact on eslint-plugin-vue in a way, as the presets offered by this plugin are named after the current priorities naming scheme.

So if we merge this, we should also adjust at least the plugin docs to mention how which preset maps to which section of the style guide.

[phanan]

I’m not familiar with eslint-plugin-vue admittedly, but all the rules are kept as-is, only re-organized.

On Sun 20. Jun 2021 at 19:29 Thorsten Lünborg @.***> wrote:

This would have an impact on eslint-plugin-vue in a way, as the presets offered by this plugin are named after the current priorities naming scheme.

So if we merge this, we should also adjust at least the plugin docs to mention how which preset maps to which section of the style guide.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/vuejs/vuejs.org/pull/2839#issuecomment-864586736, or unsubscribe https://github.com/notifications/unsubscribe-auth/AB5O3UXBQE7BAAENRCODNJLTTYQN5ANCNFSM47AEAW4A .

[LinusBorg]

To clarify:

• Right now, rules that we document as "essential" in the style guide are found in the essential preset (amongst others that are not part of the style guide, but simply enforce correct template syntax).
• rules the document as "strongly recommended" are in the strongly-recommended preset, which also includes as rules from "essential" etc.

So we might want to consider coordinating this change with a change of language in the eslint plugin to keep this relationship transparent.

Also, and this might be the bigger issue, the eslint plugin docs link back to the style guide for each rule that has a matching entry there, see for example:

https://eslint.vuejs.org/rules/component-definition-name-casing.html#further-reading

So we should take care that we either:

• have redirects in place for these URLs if this PR changes them, or:
• update the eslint docs to point to the new URLs, and do so in a synchronous manner.

[phanan]

@LinusBorg Good point. TBH I'm not sure which direction to take. @yyx990803 @ota-meshi WDYT?

[ota-meshi]

I don't think we probably need to redirect. I think we need to update the link from the eslint-plugin documentation.

I think the style guides need a "How to read the guides" section, just like the Dart documentation. https://dart.dev/guides/language/effective-dart#how-to-read-the-guides

After that, I think the eslint-plugin will need to reconfigure the presets in the next major version as follows:

• essential preset ... Follow DO and DONT.
• strongly-recommended preset ... Follow PREFER and AVOID.
• recommended preset ... Follow CONSIDER.

However, the essential preset is also used in Vetur and the user cannot change the configuration, so we need to consider what to do with items that have choices.

e.g.

DO have a consistent usage strategy for directive shorthands

Directive shorthands (: for v-bind:, @ for v-on: and # for v-slot) should be used either always or never.

https://deploy-preview-2839--vuejs.netlify.app/v2/style-guide/#DO-have-a-consistent-usage-strategy-for-directive-shorthands

I have a question that is not related to eslint. Do the DO, DONT, PREFER, AVOID, and CONSIDER categories work well with translated documents in each language? I've never translated a document so I'm not familiar with it. However, it may be difficult to put DO (etc.) to the beginning depending on the language. I thought it might affect each translation team as well.