Skip to content

Latest commit

 

History

History
128 lines (84 loc) · 6.44 KB

CONTRIBUTING.md

File metadata and controls

128 lines (84 loc) · 6.44 KB

How to contribute to Prism

First of all, thanks for considering contributing to Prism! ✨ It's people like you that make tools like Prism awesome. 💖

At Stoplight, we want contributing to Prism to be an enjoyable and educational project for everyone. Contributions go beyond commits in pull requests. We are excited to receive contributions in the form of:

  • feature ideas
  • pull requests
  • triaging issues
  • reviewing pull requests
  • implementations of Prism in your own projects
  • blog posts, talks referencing the project, tweets
  • and much more!

If it is related to Prism, we consider it a contribution.

If you are new to contributing to open source, GitHub has created a helpful guide with lots of resources here. If you want more help, post in our Community forum or send an email to support@stoplight.io. We are happy to help you out there.

We want to encourage everyone to be welcoming to newcomers and encourage new contributors from all backgrounds.

To help create an environment where anyone could potentially be welcome to contribute, we have a Code of Conduct that applies to the project and adjacent spaces related to Prism.

Stoplight Community Code of Conduct

The Stoplight Community is dedicated to providing a safe, inclusive, welcoming, and harassment-free space and experience for all community participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.

Our Code of Conduct exists because of that dedication, and we do not tolerate harassment in any form. See our reporting guidelines here. Our full Code of Conduct can be found at this link.

Development

Yarn is a package manager for your code, similar to npm. While you can use npm to use Prism in your own project, we use yarn for development of Prism.

  1. If you don't already have the yarn package manager on your machine, install yarn.
  2. Fork the https://github.com/stoplightio/prism repo.
  3. Git clone your fork (i.e. git clone https://github.com/<your-username>/prism.git) to your machine.
  4. Run yarn to install dependencies and setup the project.
  5. Because during the development we run the software directly on top of TypeScript sources, we advise you to use our script: cd packages/cli && yarn cli mock openapi.yaml.
  6. Run git checkout -b [name_of_your_new_branch] to create a new branch for your work. To help build nicer changelogs, we have a convention for branch names. Please start your branch with either feature/{branch-name}, chore/{branch-name}, or fix/{branch-name}. For example, if I was adding a CLI, I would make my branch name: feature/add-cli.
  7. Make changes, write code and tests, etc. The fun stuff!
  8. Run yarn test to test your changes.
  9. Commit your changes.
  10. Don't forget to git push to your branch after you have committed changes.

Now, you are ready to make a pull request to the Stoplight repo! 😃

If this is your first Pull Request on GitHub, here's some help.

We have a pull request template setup that you will fill out when you open your pull request.

We try to respond to all pull requests and issues within 7 days. We welcome feedback from everyone involved in the project in open pull requests.

Dependencies

If you are adding a new devDependency, add it to the root workspace package.json: yarn add -D -W {packageName}.

If you are adding a new runtime dependency, add it to the relevant package.json file (inside of prism-core, prism-http, etc).

Testing

Prism has an extensive test suite. To run it, just use the regular test script

yarn test
# or
npm test

We also have an harness test that requires some more setup. In general you do not need to run this on your computer but if you really have nothing better to do, you can run it by executing the following commands:

yarn build.binary
yarn test.harness

There's a dedicated README.MD file in the test-harness directory in case you want to know what's going on.

Debugging

The best way to debug a Prism behavior is probably to attach your debugger to the CLI and go from there. To make that happen:

cd packages/cli

yarn cli:debug mock file.oas.yml

The application will wait for a debugger to be attached and break on the first line; from there, you can put your breakpoint here and there and help us debug the software!

What is this fp-ts all about?

fp-ts is the library containing functions and data structures that help Prism lean toward a functional style. It might be annoying to step into its functions; fortunately according to your IDE, you might be able to skip the code. In case you're using Visual Studio Code, you can use the skipFiles section of your launch.json file:

{
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Launch Program",
      "skipFiles": ["node_modules/fp-ts/*.js"]
    }
  ]
}

Common issues

  1. jest --watch throws ENOSPC error
  1. I am receiving weird errors from TypeScript, but I didn't touch any part of the build process!

Prism is using TypeScript's incremental compiler capability that sometimes does not work. The best way to fix the issue is to simply remove any compiled file as well the incremental files:

rm -rf packages/**/dist
rm -rf packages/**/*.tsbuildinfo

Support

For support questions, please use the Stoplight Community forum. If you are unsure if you are experiencing a bug, the forum is a great place to start.

If you have found a bug, please create an issue.

We try to respond to all pull requests and issues within 7 days.