You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+30-14Lines changed: 30 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,7 @@
1
1
# Redocly CLI Contributing Guide
2
2
3
-
Hi! We're really excited that you are interested in contributing to Redocly CLI. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
3
+
Hi! We're really excited that you are interested in contributing to Redocly CLI.
4
+
Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
To compile the code, run `npm run compile`. To do that on the fly, run `npm run watch` in a separate thread.
50
51
51
-
To run a specific CLI command, use `npm run cli`, e.g. `npm run cli -- lint resources/museum.yaml --format=stylish`. Please notice that the extra `--` is required to pass arguments to the CLI rather than to NPM itself.
52
+
To run a specific CLI command, use `npm run cli`, e.g. `npm run cli -- lint resources/museum.yaml --format=stylish`.
53
+
Please notice that the extra `--` is required to pass arguments to the CLI rather than to NPM itself.
52
54
53
55
Format your code with `npm run prettier` before committing.
54
56
@@ -70,15 +72,15 @@ To test local changes as a package, you can use the following steps:
70
72
71
73
1. Optionally, bump the version of the packages ([see details](#version-updating)).
72
74
73
-
1. Run `npm run pack:prepare` in the repository's root. This generates **redocly-cli.tgz** and **openapi-core.tgz** files and makes some changes to **packages/cli/package.json** file.
75
+
1. Run `npm run pack:prepare` in the repository's root.
76
+
This generates **redocly-cli.tgz**, **respect-core.tgz**, and **openapi-core.tgz** files.
74
77
75
-
1. Copy **redocly-cli.tgz** file to a destination folder and then run `npm install redocly-cli.tgz` there to install Redocly CLI. To install `openapi-core` do the same but with **openapi-core.tgz** file.
76
-
77
-
Don't forget to revert the changes to **package.json** files later.
78
+
1. Copy those **.tgz** files to a destination folder and then run `npm install redocly-cli.tgz` there to install Redocly CLI. To install `openapi-core` do the same but with **openapi-core.tgz** file.
78
79
79
80
## Contribute documentation
80
81
81
-
Additions and updates to our documentation are very welcome. You can find the documentation in the `docs/` folder, and this is published to https://redocly.com/docs/cli/ as part of our main website.
82
+
Additions and updates to our documentation are very welcome.
83
+
You can find the documentation in the `docs/` folder, and this is published to https://redocly.com/docs/cli/ as part of our main website.
82
84
83
85
To preview your documentation changes locally:
84
86
@@ -92,11 +94,14 @@ redocly preview
92
94
93
95
By default, you can access the docs preview at http://localhost:4000 or http://127.0.0.1:4000.
94
96
95
-
> Please note that currently the custom markdoc tags used in the main website are not available in the local preview version, and links that point to the wider website do show as errors when using a local platform. The pull request workflows generate a full preview, so rest assured that you are able to check everything is in good shape before we review and merge your changes.
97
+
> Please note that currently the custom markdoc tags used in the main website are not available in the local preview version, and links that point to the wider website do show as errors when using a local platform.
98
+
> The pull request workflows generate a full preview, so rest assured that you are able to check everything is in good shape before we review and merge your changes.
96
99
97
100
### Prose linting
98
101
99
-
We are proud of our docs. When you open a pull request, we lint the prose using [Vale](https://vale.sh/). You can also install this tool locally and run it from the root of the project with:
102
+
We are proud of our docs.
103
+
When you open a pull request, we lint the prose using [Vale](https://vale.sh/).
104
+
You can also install this tool locally and run it from the root of the project with:
100
105
101
106
```bash
102
107
vale docs/
@@ -112,7 +117,9 @@ We use [Markdownlint](https://github.com/DavidAnson/markdownlint) to check that
112
117
113
118
### Markdown link checking
114
119
115
-
We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder. This tool runs automatically on every pull request, but you can also run it locally if you want to. Visit the project homepage to find the installation instructions for your platform, and then run the command like this:
120
+
We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder.
121
+
This tool runs automatically on every pull request, but you can also run it locally if you want to.
122
+
Visit the project homepage to find the installation instructions for your platform, and then run the command like this:
116
123
117
124
```bash
118
125
mlc docs/
@@ -122,7 +129,8 @@ It only checks links within the local docs (it can't check links to other docs s
122
129
123
130
## Built-in rules changes
124
131
125
-
After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error) and `all` rulesets with appropriate severity levels. The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
132
+
After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error) and `all` rulesets with appropriate severity levels.
133
+
The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
126
134
Also add the rule to the built-in rules list in [the config types tree](./packages/core/src/types/redocly-yaml.ts).
127
135
128
136
Separately, open a merge request with the corresponding documentation changes.
@@ -139,11 +147,16 @@ Environment variables should not affect the **core** package logic.
139
147
140
148
### Command line arguments
141
149
142
-
Use them to provide some arguments that are specific to a certain command. Think of them as modifiers. They should not affect the **core** package logic.
150
+
Use them to provide some arguments that are specific to a certain command.
151
+
Think of them as modifiers.
152
+
They should not affect the **core** package logic.
143
153
144
154
### Configuration file
145
155
146
-
The **redocly.yaml** file is the most flexible way of providing arguments. Please use it to provide arguments that are common for all the commands, for a specific command, or for a specific API. It could be used for providing arguments for both **cli** and **core** packages. Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.
156
+
The **redocly.yaml** file is the most flexible way of providing arguments.
157
+
Please use it to provide arguments that are common for all the commands, for a specific command, or for a specific API.
158
+
It could be used for providing arguments for both **cli** and **core** packages.
159
+
Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.
147
160
148
161
## Exit codes
149
162
@@ -217,14 +230,17 @@ If you made any changes, make sure to compile the code before running the tests.
217
230
-**`packages/core/src/types`**: contains the common types for several OpenAPI versions.
218
231
-**`packages/core/src/typings`**: contains the common Typescript typings.
219
232
233
+
-**`packages/respect-core`**: contains the Respect core package.
234
+
220
235
-**`resources`**: contains some example API descriptions and configuration files that might be useful for testing.
221
236
222
237
## Release flow
223
238
224
239
We use [Changesets](https://github.com/changesets/changesets) flow.
225
240
After merging a PR with a changeset, the release PR is automatically created.
226
241
227
-
If the pipelines are not starting, close and reopen the PR. Merging that PR triggers the release process.
242
+
If the pipelines are not starting, close and reopen the PR.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments