[docs-infra] Share vale-config

[alexfauquette]

Implemented

The common style rules are in docs/writing-rules To update them, you need to modify the files, and run pnpm run docs:zipRules that will update the writing-rules.zip which is used by vale (for this repo and others)

Also added in this PR:

• Some rules for charts
• the correction 'server side' -> 'server-side' and 'client side' -> 'client-side' from toolpad

Initial message

I would like to create a vale package to get a single source of truth about our writing style. For now, we need to duplicate PR to sync core and X

I planed to use the monorepo trick, but the vale action does not install dependencies so the monorepo is not added.

We could:

Option 1

Add a yarn install phase in vale action do download the monorepo

I'm not in favor of this one since it's downloading lost of thing just to get few files

Option 2

Move vale rules to a distinct repository such that it could have a release that generate a .zip files

The drawback of this option is that you can't directly test modification on the docs. But we could create few markdown documents for testing purpose

Option 3

Have a storage option to publish and download a zip file containing the syntax rules.

@mui/code-infra I don't know if it resonates with some of your discussion. I assume no, because this is one of the rare piece of the repo that is not JS

[mui-bot]

Netlify deploy preview

https://deploy-preview-41176--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 702d39b

[Janpot]

option 4

Store the zip file in the repository and update it manually before pushing changes with a script. Have a CI check that verifies the zip is up to date. Then use raw github link to load in dependent repos. (Q: how big is this zip file expected to be?)

[alexfauquette]

@Janpot It's currently a baby of 3.1kB obtained by runnign zip -r "writing-rules.zip" docs/writing-rules on this branch

[Janpot]

@Janpot It's currently a baby of 3.1kB obtained by runnign zip -r "writing-rules.zip" docs/writing-rules on this branch

thanks, seems reasonable enough to store it in the repo itself imo

[alexfauquette]

@Janpot I did not add the check to see if the zip is up to date, because I'm wondering if the zip will be independent on the system generating it, and I made vale use directly the zip such that the zip file is the source of truth (not the yml files)

[Janpot]

Is it possible to embed the Google package in docs/writing-rules.zip?

[alexfauquette]

Did not tried. Maybe

What would be the usage of adding Google here? Simplifying the .vale.ini to just importing this zip?

[Janpot]

Simplifying the .vale.ini to just importing this zip?

Yes, making the setup on dependent repos as small as possible. I mean, I'm assuming that the Google guide is what we start from for our own writing style.

[alexfauquette]

Yes, we started with the basics Google rules we wanted to pick.

I prefer to keep them distinct, such that in material-ui repo we store the rules, and then each sub repo are able to configure its vale as they want by allowing or not different rules

[Janpot]

I prefer to keep them distinct, such that in material-ui repo we store the rules, and then each sub repo are able to configure its vale as they want by allowing or not different rules

Is it possible for material-ui repo to provide the Google defaults and X/Toolpad override where necessary? That would allow @samuelsycamore to maintain the these defaults in a single location as well.

[samuelsycamore]

In the interest of consistency, I think it would be preferable not to have overrides at the product level—any style rules we use should be applied globally. I can't think of a reason why one product would add or remove rules that shouldn't also apply to all of the other products.

[alexfauquette]

Ok, I created https://github.com/mui/material-ui/issues/41225 to don't forget. I will take care of it after cleaning all the PR already open :)

[Janpot]

@Janpot I did not add the check to see if the zip is up to date, because I'm wondering if the zip will be independent on the system generating it, and I made vale use directly the zip such that the zip file is the source of truth (not the yml files)

👍 as long as there are good instructions. Another option is to unpack the zip and compare the result with the original folder.

[oliviertassinari]

I think we should go with a variant of Option 1: install the one dependency we need.

I don't think it will work in the current setup as I'm moving to implement "Causes CI/CD jobs to fail" https://docs.gitlab.com/ee/development/documentation/testing/vale.html#result-types. Either we use HEAD but we lose idempotence ❌, or we set a tag but we have to remember to update it ❌.

[Janpot]

or we set a tag but we have to remember to update it ❌.

I believe this can be automated with renovatebot https://docs.renovatebot.com/presets-regexManagers/

[oliviertassinari]

@Janpot it's another degree of freedom, eww, but if this is batched in renovate, and it means the Vale step runs in 40s rather than 120s, it could be worth it.

If we ever need to run pnpm in the GitHub Actions, maybe like in Circle CI it makes sense to have a shared cache. We do for instance here https://github.com/mui/mui-x/blob/0dc41910f86e11cef96d0f1db7b1af8cfbcc8a63/.github/workflows/l10n.yml#L26. It costs about 60s.

In any case, I think think we can wait for the problem to happen. Right now, I'm only working on failing the CI for the diffs that are in the PR, not for the whole codebase #40944. So it feels like something we should be lazy about.