Skip to content

Latest commit

 

History

History
204 lines (127 loc) · 9.49 KB

CONTRIBUTING.md

File metadata and controls

204 lines (127 loc) · 9.49 KB
Raw

Redocly CLI Contributing Guide

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.

Issue Reporting Guidelines

  • Before opening a new issue, try to make sure the same problem or idea hasn't already been reported. You can do that on the Issues page in the repository and using the filter is:issue combined with some keywords relevant to your idea or problem. It helps us notice that more people have the same issue or use-case, and reduces the chance of getting your issue marked as a duplicate. Plus, you can even find some workarounds for your issue in the comments of a previously reported one!

  • The best way to get your bug fixed is to provide a (reduced) test case. This means listing and explaining the steps we should take to try and hit the same problem you're having. It helps us understand in which conditions the issue appears, and gives us a better idea of what may be causing it.

  • Abide by our Code of Conduct in all your interactions on this repository, and show patience and respect to other community members.

Pull Request Guidelines

Before submitting a pull request, please make sure the following is done:

  1. Fork the repository and create your branch from main.
  2. Run npm install in the repository root.
  3. If you’ve fixed a bug or added code that should be tested, don't forget to add tests!
  4. Ensure the test suite passes (npm test). Tip: npm test -- --watch TestName is helpful in development.
  5. Format your code with prettier (npm run prettier).
  6. Each feat/fix PR should also contain a changeset (to create one, run npx changeset; if your changes are scoped to packages/core but also affect Redocly CLI behavior, please include the @redocly/cli package as well). Please describe what you've done in this PR using sentence case (you can refer to our changelog). This produces a file in .changeset folder. Please commit this file along with your changes.

Development Setup

Node.js at v14.19.0+ and NPM v7.0.0+ are required.

After forking the repo, run:

$ npm install # or npm i

Commonly used NPM scripts

# run a separate CLI command
$ npm run <command>

# run a compile of packages
$ npm run compile

# synchronously pick-up the changes made to the packages
$ npm run watch

# run the CLI package
$ npm run cli

# run the unit tests with typecheck
$ npm test

# run the unit tests (includes coverage report)
$ npm run unit

# run e2e tests
$ npm run e2e
# Make sure you have compiled the code before running e2e test
# E.g. run `npm run compile` and wait for the finishing process or run `npm run watch`.

# format the code using prettier
$ npm run prettier

# run basic perf benchmark
$ npm run benchmark

There are some other scripts available in the scripts section of the package.json file.

Local source code usage

NPM linking

To test the local source code of the packages in other local applications, you can use npm linking. See the docs.

Local packing and installing

To test local changes as a package, you can use the following steps:

  1. Optionally, bump the version of the packages (see details).

  2. 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.

  3. 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.

Don't forget to revert the changes to package.json files later.

Contribute documentation

Prose linting

We are proud of our docs. When you open a pull request, we lint the prose using Vale. You can also install this tool locally and run it from the root of the project with:

vale docs/

The configuration is in .vale.ini in the root of the project.

Markdown link checking

We use 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:

mlc docs/

It only checks links within the local docs (it can't check links to other docs sections that are present when we publish all products under https://redocly.com/docs), and doesn't currently check anchors, so take care when renaming pages or titles.

Built-in rules changes

After adding a new rule, make sure it is added to the minimal, recommended and all rulesets with appropriate severity levels. The defaults are off for minimal and recommended and error for all. Also add the rule to the builtInRulesList in the config types tree.

Separately, open a merge request with the corresponding documentation changes.

Arguments usage

There are three ways of providing arguments to the CLI: environment variables, command line arguments, and Redocly configuration file.

Environment variables

Environment variables should be used to provide some arguments that are common for all the commands. We always prefer configuration over environment variables. Environment variables should not affect the core package logic.

Command line arguments

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.

Configuration file

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 documentation for more details.

Exit codes

The application maintains the following exit codes.

Exit code Description
0 Success
1 Command execution error
2 Config resolving failure

Tests

Unit tests

Unit tests in the cli package are sensitive to top-level configuration file (redocly.yaml).

To get coverage per package run npm run coverage:cli or npm run coverage:core.

E2E tests

E2E tests are sensitive to any additional output (like console.log) in the source code.

Project Structure

  • __mocks__: contains basic mocks for e2e tests.

  • __tests__: contains e2e tests. The e2e tests are written and run with Jest.

  • docs: contains the documentation source files. When changes to the documentation are merged, they automatically get published on the Redocly docs website.

  • packages: contains the source code. Сonsists of two packages - CLI and core. The codebase is written in Typescript.

    • packages/cli: contains Redocly CLI commands and utils. More details here.

      • packages/cli/src: contains CLI package source code.

        • packages/cli/src/__mocks__: contains basic mocks for unit tests.
        • packages/cli/src/__tests__: contains unit tests.
        • packages/cli/src/commands: contains CLI commands functions.

    • packages/core: contains Redocly CLI core functionality like rules, decorators, etc.

      • packages/core/__tests__: contains unit tests.

      • packages/cli/core: contains core package source code.

        • packages/core/src/__tests__: contains unit tests.
        • packages/core/src/benchmark: contains basic perf benchmark. Not fully ready yet.
        • packages/core/src/config: contains the base configuration options.
        • packages/core/src/decorators: contains the built-in decorators code.
        • packages/core/src/format: contains the format options.
        • packages/core/src/js-yaml: contains the JS-YAML based functions.
        • packages/core/src/redocly: contains the Redocly API registry integration setup.
        • packages/core/src/rules: contains the built-in rules code.
        • packages/core/src/types: contains the common types for several OpenAPI versions.
        • packages/core/src/typings: contains the common Typescript typings.

  • resources: contains some example API descriptions and configuration files that might be useful for testing.

Release flow

We use Changesets flow. After merging a PR with a changeset, the release PR is automatically created.

If the pipelines are not starting, close and reopen the PR. Merging that PR triggers the release process.