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

docs(repo): update rulesets loading procedure #1797

Merged
merged 5 commits into from
Sep 15, 2021
Merged

docs(repo): update rulesets loading procedure #1797

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8a26c76
docs(repo): update rulesets loading procedure
P0lip Aug 31, 2021
a10edea
Merge branch 'develop' into docs/default-ruleset-note
mnaumanali94 Sep 15, 2021
99098c5
docs(repo): update rulesets loading procedure
P0lip Aug 31, 2021
49d26a0
docs: readme.md
P0lip Sep 15, 2021
37f776b
revert: woops
P0lip Sep 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,18 @@ yarn global add @stoplight/spectral-cli

Find more [installation methods](https://meta.stoplight.io/docs/spectral/docs/getting-started/2-installation.md) in our documentation.

**Create a Ruleset**

Spectral, being a generic YAML/JSON linter, needs a ruleset in order to be able to lint files.
You can learn more about the rulesets [here](./docs/getting-started/3-rulesets.md).

If you intend to lint an OpenAPI or AsyncAPI document, we have a few predefined rulesets you can extend to get Spectral up and running.
To reference them, you can run the following command:

```bash
echo '{\n\t"extends": ["spectral:oas", "spectral:asyncapi"]\n}' > .spectral.json
```

Copy link
Contributor

Choose a reason for hiding this comment

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

Also add a callout to say that this is a breaking change moving to V6

**Lint**

```bash
Expand Down
3 changes: 2 additions & 1 deletion docs/guides/2-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@ The Spectral CLI supports loading documents as YAML or JSON, and validation of O

## Using a Ruleset File

If you don't specify a ruleset file with the `--ruleset` parameter, the Spectral CLI will look for a ruleset file called `.spectral.yml`, `.spectral.yaml`, or `.spectral.json` in the current working directory. If no ruleset is specified and no default ruleset file is found, the built-in rulesets will be used.
If you don't specify a ruleset file with the `--ruleset` parameter, the Spectral CLI will look for a ruleset file called `.spectral.yml`, `.spectral.yaml`, `.spectral.json` or `.spectral.js` in the current working directory.
Spectral will refuse to lint the document if no ruleset is specified and no default ruleset file is found.
Copy link
Contributor

Choose a reason for hiding this comment

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

If this is meant to be a new paragraph it will need another line.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We can have a separate paragraph, sure.

Suggested change
Spectral will refuse to lint the document if no ruleset is specified and no default ruleset file is found.
Spectral will refuse to lint the document if no ruleset is specified and no default ruleset file is found.
If you want to have a simple basic ruleset for OpenAPI, this command will let you get started:
`echo "extends: spectral:oas" > .spectral.yaml`

@philsturgeon thoughts?

Copy link
Contributor

Choose a reason for hiding this comment

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

Is this new behavior in Spectral v6? We used to autodetect and apply OAS if we thought it was OAS, but now folks have to specify that for theirselves?

Copy link

Choose a reason for hiding this comment

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

I just ran up against this change and found this confusing behaviour. A few other people in #1796 had a similar experience from the sound of things.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ooops, I lost sight of these comments.

Is this new behavior in Spectral v6? We used to autodetect and apply OAS if we thought it was OAS, but now folks have to specify that for theirselves?

Yeah, it's a deliberate change we've made.
Overall, from a technical standpoint it is quite trivial to load some default ruleset - would probably be like a one-liner kind of a change if we were to make it, so totally straightforward to do.
Our goal was to convince users to write their own style guides, but I'm all in for constant reiteration of the standpoint if this happens to be truly annoying - I believe that most of folks do have some kind of a ruleset, so this change is seamless for them.

Copy link
Contributor

Choose a reason for hiding this comment

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

Ok, thanks for clarifying.


Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or extend and modify our core rulesets:

Expand Down