Skip to content

Latest commit

 

History

History
104 lines (67 loc) · 5.5 KB

CONTRIBUTING.md

File metadata and controls

104 lines (67 loc) · 5.5 KB
Raw

Contributing

Running Shell Commands Locally 🐚

To get started, run the build script to create a symlink with package.json (required for our oclif setup to read our commands properly). You only need to do this the first time you clone the repository.

npm run build

To run test commands, swap out rdme for bin/dev.js. For example:

# if the production command you're testing looks like this...
rdme openapi:validate __tests__/__fixtures__/ref-oas/petstore.json

# ... your local test command will look like this:
bin/dev.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json

The bin/dev.js file has a few features that are useful for local development:

  • It reads directly from your TypeScript files (so no need to re-run the TypeScript compiler every time you make a change)
  • It returns error messages with full stack traces

bin/dev.js is convenient for useful for rapid development but it's not a 1:1 recreation of what the end-user experience with rdme is like. To recreate the production rdme experience, use the bin/run.js file instead. You'll need to re-run the TypeScript compiler (i.e., npm run build) every time you make a change. So for example:

npm run build
bin/run.js openapi:validate __tests__/__fixtures__/ref-oas/petstore.json

Your changes to the command code may make changes to the command reference documents — it is up to you whether you include those changes in your PR or if you let the release process take care of it. More information on that can be found in MAINTAINERS.md.

Running GitHub Actions Locally 🐳

To run GitHub Actions locally, we'll be using act (make sure to read their prerequisites list and have that ready to go before installing act)!

Unfortunately (as of this writing), the maintainer hasn't tagged a release that includes PR #793, which is required for running the composite action setup we have defined in action.yml. You'll need to install act with the --HEAD flag:

brew install act --HEAD

As of this writing, this is the version of act that is able to successfully run our workflows (i.e. the output of the act --version command):

# https://github.com/nektos/act/commit/9abc87b
act version HEAD-9abc87b

Once you've installed act, it'll ask you what Docker image size you'd like. The standard Medium ones should do the trick. Here's what your ~/.actrc file should look like:

-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04
-P ubuntu-18.04=ghcr.io/catthehacker/ubuntu:act-18.04

Our GitHub Actions guidance states that Action workflows should have a runs-on value of ubuntu-latest. These runners are updated frequently — you can find links to the latest versions by navigating here and selecting the latest Ubuntu link. Because of this, you'll want to make sure your ghcr.io/catthehacker/ubuntu image stays up-to-date by doing a periodic pull:

docker pull ghcr.io/catthehacker/ubuntu:act-latest

Once it's configured, you can use the -l flag to to view all the workflows:

act -l # all workflows with the default event (i.e. `push`)
act workflow_dispatch -l # all workflows with the `workflow_dispatch` event

Running the latter command will return the following:

Stage  Job ID  Job name                 Workflow name                 Workflow file  Events
0      simple  GitHub Action Auth-Less  GitHub Action Simple Example  simple.yml     workflow_dispatch

And finally, you can use that Job ID to execute a workflow with the -j flag (make sure Docker is running!):

act -j simple

Code Style Guidelines

Usage of console

As you'll learn in our commands logic (see bin/run.js and the src/commands directory), we wrap our command outputs in resolved/rejected Promise objects and use bin/run.js file to log the results to the console and return the correct status code. This is so we can write more resilient tests, ensure that the proper exit codes are being returned, and make debugging easier.

When writing command logic, avoid using console statements (and correspondingly, avoid mocking console statements in tests) when possible.

Making fetch requests

fetch requests are very common in this codebase. When sending fetch requests to the ReadMe API (i.e., dash.readme.com), make sure to use the fetch wrapper function located in src/lib/readmeAPIFetch.ts. We have an ESLint rule to flag this.

In that wrapper function, we set several important request headers and configure the proxy, if the user added one via HTTPS_PROXY.

Commit Conventions

For our general commit conventions, please consult our organization contributing guidelines here.