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.

Sign up for GitHub

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

Jump to bottom

Make the Vale prose linter required #47907

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Make the Vale prose linter required #47907

wants to merge 1 commit into from

Conversation

ptgott
Copy link
Contributor

@ptgott ptgott commented Oct 24, 2024 •
edited
Loading

Make the Vale prose linter required

This change makes the prose linting step part of the required Lint
(Docs) job.

As of Vale 3.8.0, it is possible to set custom comment delimiters so an
author can temporarily disable a style rule within an MDX docs page. For
example, an author can ignore the protocol-products rule by including
this:

{/* vale messaging.protocol-products = NO */}

This paragraph is about server access.

{/* vale messaging.protocol-products = YES */}

This change updates the version of Vale used by the linting job to
3.9.0, and includes custom comment delimiters in the configuration.

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-eoprbue73-goteleport.vercel.app/docs/ver/preview

@ptgott ptgott added the no-changelog Indicates that a PR does not require a changelog entry label Oct 24, 2024
@aws-amplify-us-west-2 AWS Amplify (us-west-2)
Copy link

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-47907.d212ksyjt6y4yg.amplifyapp.com

@ptgott ptgott mentioned this pull request Oct 25, 2024
Draft
mmcallister
mmcallister approved these changes Oct 28, 2024
View reviewed changes
Copy link
Contributor

@mmcallister mmcallister left a comment

Choose a reason for hiding this comment

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

awesome, this will save folks a lot of time!

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from e8dd631 to f789367 Compare October 30, 2024 20:32
@aws-amplify-us-west-2 AWS Amplify (us-west-2)
Copy link

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-47907.d3pp5qlev8mo18.amplifyapp.com

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-pft7e7o94-goteleport.vercel.app/docs/ver/preview

@mmcallister
Copy link
Contributor

How do we feel about removing the ban on the word 'simple' from the vale subjective terms, since we're looking to make prose linter required soon? On one hand I can see the word not really being needed, but on the other I think it can put new users at ease depending on context. Some examples:

The http://127.0.0.1:3000/healthz endpoint responds with a body of {"status":"ok"} and an HTTP 200 OK status code if the process is running. This is a simple check, suitable for determining if the Teleport process is still running.

Create an API user using a simple role-based authentication method.

Next, we'll create a simple access list that will grant the access role to its members..

@ptgott
Copy link
Contributor Author

ptgott commented Oct 31, 2024 •
edited
Loading

@mmcallister Personally, I'm not a fan of "simple", since a docs author can't know everything about the reader's infrastructure, professional experience, organizational constraints, etc. For me, assuring the reader that something is simple doesn't help it appear simpler, and can risk being alienating. I think all of the examples above make as much sense without "simple". If we're divided on it, though, I think it makes sense to change the rule's level to warning and soften the message a bit, if that sounds okay to you!

Edit: The rule was already at the warning level, but I softened the language a bit in db73f44.

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from f789367 to db73f44 Compare October 31, 2024 18:16
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-3ijej2l4p-goteleport.vercel.app/docs/ver/preview

@github-actions GitHub Actions
Copy link

github-actions bot commented Nov 4, 2024

🤖 Vercel preview here: https://docs-p4hv7946r-goteleport.vercel.app/docs/ver/preview

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from a8f001b to 945b97f Compare November 5, 2024 20:09
@github-actions GitHub Actions
Copy link

github-actions bot commented Nov 5, 2024

🤖 Vercel preview here: https://docs-523pd88wv-goteleport.vercel.app/docs/ver/preview

@espadolini espadolini removed their request for review November 7, 2024 09:28
@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from 945b97f to 008e9e8 Compare November 11, 2024 20:36
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-8jlkxz67t-goteleport.vercel.app/docs/ver/preview

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from 008e9e8 to 7142973 Compare November 12, 2024 20:41
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-96xudrd4r-goteleport.vercel.app/docs/ver/preview

@ptgott ptgott marked this pull request as draft November 12, 2024 21:12
@ptgott
Copy link
Contributor Author

ptgott commented Nov 12, 2024 •
edited
Loading

Putting this in draft while I split up this PR into smaller PRs to make review easier:

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from 7142973 to d436555 Compare December 2, 2024 19:43
@github-actions GitHub Actions
Copy link

github-actions bot commented Dec 2, 2024

🤖 Vercel preview here: https://docs-2qga2vz12-goteleport.vercel.app/docs

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from d436555 to 9ff8b17 Compare December 4, 2024 20:10
@ptgott ptgott marked this pull request as ready for review December 4, 2024 20:11
@github-actions GitHub Actions
Copy link

github-actions bot commented Dec 4, 2024

🤖 Vercel preview here: https://docs-plrjf4wga-goteleport.vercel.app/docs

@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from 9ff8b17 to 217abcc Compare December 11, 2024 18:42
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-98nxsqqve-goteleport.vercel.app/docs

@ptgott
Make the Vale prose linter required
5478b5a 
This change makes the prose linting step part of the required Lint
(Docs) job.

As of Vale 3.8.0, it is possible to set custom comment delimiters so an
author can temporarily disable a style rule within an MDX docs page. For
example, an author can ignore the `protocol-products` rule by including
this:

```text
{/* vale messaging.protocol-products = NO */}

This paragraph is about server access.

{/* vale messaging.protocol-products = YES */}
```

This change updates the version of Vale used by the linting job to
3.9.0, and includes custom comment delimiters in the configuration.
@ptgott ptgott force-pushed the paul.gottschling/2024-10-23-require-vale branch from 217abcc to 5478b5a Compare December 13, 2024 21:07
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-1k3dz6mby-goteleport.vercel.app/docs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@klizhentas klizhentas Awaiting requested review from klizhentas klizhentas is a code owner

@russjones russjones Awaiting requested review from russjones russjones is a code owner

@r0mant r0mant Awaiting requested review from r0mant r0mant is a code owner

@zmb3 zmb3 Awaiting requested review from zmb3 zmb3 is a code owner

@fheinecke fheinecke Awaiting requested review from fheinecke fheinecke is a code owner

@camscale camscale Awaiting requested review from camscale camscale is a code owner

@tcsc tcsc Awaiting requested review from tcsc tcsc is a code owner

@rosstimothy rosstimothy Awaiting requested review from rosstimothy rosstimothy is a code owner

@codingllama codingllama Awaiting requested review from codingllama codingllama is a code owner

@mvbrock mvbrock Awaiting requested review from mvbrock

@xinding33 xinding33 Awaiting requested review from xinding33

@eriktate eriktate Awaiting requested review from eriktate

@mmcallister mmcallister Awaiting requested review from mmcallister

At least 2 approving reviews are required to merge this pull request.

Assignees
No one assigned
Labels
documentation no-changelog Indicates that a PR does not require a changelog entry size/sm
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@ptgott @mmcallister