diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f4a9e5d1..27fce98b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,123 @@ -# Contributing +# How to contribute to Prism -## Setup +First of all, thanks for considering contributing to Prism! ✨ It's people like you that make tools like Prism awesome. 💖 -1. Clone the repository -2. Run `yarn` -3. Reference the bin directly, for example `./packages/cli/bin/run mock openapi.yaml` +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](https://opensource.guide/how-to-contribute/). If you want more help, post in our [Community forum](https://community.stoplight.io/c/open-source) or send an email to [support@stoplight.io](mailto: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](https://github.com/stoplightio/code-of-conduct/blob/master/incident-reporting.md). Our full Code of Conduct can be found at this [link](https://github.com/stoplightio/code-of-conduct/blob/master/long-form-code-of-conduct.md#long-form-code-of-conduct). + +## 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](https://yarnpkg.com/lang/en/docs/install/). +2. Fork the [https://github.com/stoplightio/prism](https://github.com/stoplightio/prism) repo. +3. Git clone your fork (i.e. `git clone https://github.com//prism.git`) to your machine. +4. Run `yarn` to install dependencies and setup the project. +5. Reference the bin directly, for example `./packages/cli/bin/run 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](https://egghead.io/lessons/javascript-how-to-create-a-pull-request-on-github). + +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. + +### Testing + +Prism has an extensive test suite. To run it, just use the regular `test` script + +```bash +yarn test +# or +npm test +``` + +### 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: + +```bash +cd packages/cli + +node --inspect-brk -r tsconfig-paths/register bin/run 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! + +### Common issues + +1. `jest --watch` throws ENOSPC error + +- [optional] Install `watchman` as per [documentation](https://facebook.github.io/watchman/docs/install.html#installing-from-source) +- Modify `fs.inotify.max_user_watches` as per [issue resolution](https://github.com/facebook/jest/issues/3254) + +## Creating an issue + +We want to keep issues in this repo focused on bug reports and feature requests. + +For support questions, please use the [Stoplight Community forum](https://community.stoplight.io/c/open-source). If you are unsure if you are experiencing a bug, the [forum](https://community.stoplight.io/c/open-source) is a great place to start. + +Before you open an issue, try to see if anyone else has already opened an issue that might be similar to your issue or feature request. Start by commenting there to see if you are having the same issue or feature request. + +We have an issue template setup: + +``` +### **I'm submitting a...** + - bug report + - feature request + +### What is the current behavior? + +If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem. + +### What is the expected behavior? + +### What is the motivation / use case for changing the behavior? + +### Please tell us about your environment: + + - Version: 2.0.0-beta.X + - Framework: [ ] + - Language: [all | TypeScript X.X | ES6/7 | ES5 | Dart] + +### Other information + +(e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. stackoverflow, issues outside of the repo, forum, etc.) +``` + +We realize there is a lot of data requested here. We ask only that you do your best to provide as much information as possible so we can better help you. + +## Support + +For support questions, please use the [Stoplight Community forum](https://community.stoplight.io/c/open-source). If you are unsure if you are experiencing a bug, the [forum](https://community.stoplight.io/c/open-source) 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. diff --git a/README.md b/README.md index ae9bd7db9..13fce6f87 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,24 @@ -Prism is a set of packages that relate to API specification mocking. One use case, spinning up a mock HTTP server which will response realistically to the requests you send it. +Prism is a set of packages for API mocking with **OpenAPI Specification v2** (formerly known as Swagger Specification) and **OpenAPI Specification v3**. -**Note: this branch refers to Prism 3.x, which is the current version most likely you will use. If you're looking for the 2.x version, point your browser to the [right branch][2.x]** +For example, given an API specification: -Being based on [Graphite], Prism supports any description format that Graphite supports: +- You can spin up a mock HTTP server and respond realistically based on your requests -- OpenAPI v3.0 -- OpenAPI v2.0 (formerly Swagger) +The set of packages are made up of: -Prims is a multi-package repository: +- [`core`][core]: basic interfaces and abstraction for API descriptions +- [`http`][http]: A Prism implementation to work with HTTP Requests +- [`http-server`][http-server]: A _[Fastify]_ instance that uses Prism to validate/mock/respond and forward to http requests +- [`cli`][cli]: A CLI to spin up servers locally easily -- [`core:`][core] basic interfaces and abstraction for API descriptions -- [`http:`][http] A Prism implementation to work with HTTP Requests -- [`http-server:`][http-server] A _[Fastify]_ instance that uses Prism to validate/mock/respond and forward to http requests -- [`cli:`][cli] A CLI to spin up servers locally easily +Look at the relative repositories' READMEs for the specific documentation. -Look at the relative repositories' README for the specific documentation. +> Note: This branch refers to Prism 3.x, which is the current version most likely you will use. If you're looking for the 2.x version, point your browser to the [2.x branch][2.x] -## Install +## Installation Most of the users will probably want to use the CLI, which is a Node module, and can either be installed via NPM or Yarn… @@ -36,7 +35,7 @@ yarn global add @stoplight/prism-cli ### CLI -We'll present here only the main use cases. For a complete overview of the CLI, you can consult the relevant [documentation][cli-docs] +We'll present here only the main use cases. For a complete overview of the CLI, you can consult the relevant [documentation][cli-docs]. #### Mock server @@ -110,12 +109,6 @@ Connection: keep-alive This error shows the request is missing a required property `name` from the HTTP request body. -## FAQ - -Base paths are completely ignored by the Prism HTTP server, so they can be removed from the request. -If you have a base path of `/api` and your path is defined as `hello`, then a request to -`http://localhost:4010/hello` would work, but `http://localhost:4010/api/hello` will fail. - ## What's next for Prism? - [ ] Server Validation @@ -126,45 +119,22 @@ If you have a base path of `/api` and your path is defined as `hello`, then a re - [ ] Forwarding proxy with validation - [ ] Recording traffic to spec file - [ ] Data Persistence (turn Prism into a sandbox server) -- [ ] Support files ending with `.yml` and extensionless files - -## Testing - -Prism has an extensive test suite. To run it, just use the regular `test` script - -```bash -yarn test -# or -npm test -``` +- [ ] Support files ending with `.yml` and extension-less files -## Debugging +## FAQs -The best way to debug a Prism behaviour is probably to attach your debugger to the CLI and go from there. To make that happen: - -```bash -cd packages/cli - -node --inspect-brk -r tsconfig-paths/register bin/run 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! +Base paths are completely ignored by the Prism HTTP server, so they can be removed from the request. +If you have a base path of `/api` and your path is defined as `hello`, then a request to +`http://localhost:4010/hello` would work, but `http://localhost:4010/api/hello` will fail. ## Contributing -Please see [CONTRIBUTING] and [CODE_OF_CONDUCT] for details. - -### Common issues - -1. `jest --watch` throws ENOSPC error - -- [optional] Install `watchman` as per [documentation](https://facebook.github.io/watchman/docs/install.html#installing-from-source) -- Modify `fs.inotify.max_user_watches` as per [issue resolution](https://github.com/facebook/jest/issues/3254) +If you are interested in contributing to Prism itself, check out our [contributing docs][contributing] and [code of conduct][code_of_conduct] to get started. -[CODE_OF_CONDUCT]: CODE_OF_CONDUCT.md -[CONTRIBUTING]: CONTRIBUTING.md -[Fastify]: https://www.fastify.io/ -[Graphite]: https://github.com/stoplightio/graphite +[code_of_conduct]: CODE_OF_CONDUCT.md +[contributing]: CONTRIBUTING.md +[fastify]: https://www.fastify.io/ +[graphite]: https://github.com/stoplightio/graphite [download-release]: https://github.com/stoplightio/prism/releases/latest [rfc7807]: https://tools.ietf.org/html/rfc7807 [core]: https://www.npmjs.com/package/@stoplight/prism-core