Skip to content

Commit

Permalink
docs: updated contributing.md and readme.md (stoplightio#282)
Browse files Browse the repository at this point in the history 
* docs: updated contributing.md and readme.md

* docs: fix clone example

* Update README.md

Co-Authored-By: Phil Sturgeon <me@philsturgeon.uk>

* Update README.md

Co-Authored-By: Phil Sturgeon <me@philsturgeon.uk>
  • Loading branch information
@tbarn
tbarn and Phil Sturgeon committed May 10, 2019
1 parent f62655f commit 02e2511
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 57 deletions.
126 changes: 121 additions & 5 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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/<your-username>/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.
74 changes: 22 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,24 @@

<a href="https://codeclimate.com/github/stoplightio/prism/test_coverage"><img src="https://api.codeclimate.com/v1/badges/f5e363a7eb5b8f4e570f/test_coverage" /></a>

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…

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 02e2511

Please sign in to comment.