docs(CONTRIBUTING): reword creating issues section

* Separate between feature request and bug report
* Add links to playground (JSFiddle)
This commit is contained in:
Nico Rehwaldt 2017-09-26 11:50:51 +02:00 committed by Nico Rehwaldt
parent 22c628a056
commit 5a93dbe1b7
1 changed files with 63 additions and 18 deletions

View File

@ -1,22 +1,59 @@
# How to contribute
# How to Contribute
We love you to contribute to this project by filing bugs, helping others on the [issue tracker](https://github.com/bpmn-io/bpmn-js/issues), by contributing features/bug fixes through pull requests or by helping out in our [forums](https://forum.bpmn.io/).
Great to see you! Help us out by [filing bugs or feature requests](#working-with-issues), assisting others in our [forums](https://forum.bpmn.io/) or by [contributing improvements](#contributing-improvements).
## Creating issues
## Table of Contents
We use our [issue tracker](https://github.com/bpmn-io/bpmn-js/issues) for project communication.
When using the issue tracker:
* [Working with Issues](#working-with-issues)
* [Creating an Issue](#creating-an-issue)
* [Helping out](#helping-out)
* [Contributing Improvements](#contributing-improvements)
* [Setting up the Project locally](#setting-up-the-project-locally)
* [Discussing Code Changes](#discussing-code-changes)
* [Creating a Pull Request](#creating-a-pull-request)
* Be descriptive when creating an issue (what, where, when and how does a problem pop up)?
* Attach steps to reproduce (if applicable)
* Attach code samples, configuration options or stack traces that may indicate a problem
## Working with Issues
We use our [issue tracker](https://github.com/bpmn-io/bpmn-js/issues) for project communication, discussion and planning.
### Creating an Issue
Help others to understand your request:
* Be clear whether you [file a bug](#reporting-a-bug) or [suggest a new feature/improvement](#suggesting-a-feature)
* Be descriptive when reporting (what, where, when and how)
#### Reporting a Bug
Help us to understand and reproduce your issue:
* Attach your environment (browser, bpmn-js version)
* Attach steps to reproduce
* Attach code samples, configuration options or stack traces that provide the necessary context
If possible, try to build an example that reproduces your problem. Use [this JSFiddle](https://jsfiddle.net/kxqy09gf/) as a starting point or put a running demo up on [GitHub](https://github.com/).
#### Suggesting a Feature
* Provide the necessary context that allows us to understand how your proposal improves our library
### Helping out
* Share your perspective on issues
* Be helpful and respect others when commenting
Create a pull request if you would like to have an in-depth discussion about some piece of code.
## Contributing Improvements
## Setting up the project locally
Learn how to setup the project locally, make changes and contribute bug fixes and new features through pull requests.
### Setting up the Project
The project development runs on top of the [diagram-js](https://github.com/bpmn-io/diagram-js) master branch. The following code snippet sets up both libraries linking diagram-js to bpmn-js.
@ -30,15 +67,20 @@ The project development runs on top of the [diagram-js](https://github.com/bpmn-
(cd bpmn-js && npm install && npm link ../diagram-js)
// Run the test suite
grunt
npm test
// Running the test suite with every file change
TEST_BROWSERS=(Chrome|Firefox|IE) grunt auto-test
TEST_BROWSERS=(Chrome|Firefox|IE) npm run dev
## Creating pull requests
### Discussing Code Changes
We use pull requests for feature discussion and bug fixes. If you are not yet familiar on how to create a pull request, [read this great guide](https://gun.io/blog/how-to-github-fork-branch-and-pull-request).
Create a [pull request](#creating-a-pull-request) if you would like to have an in-depth discussion about some piece of code.
### Creating a Pull Request
We use pull requests for feature additions and bug fixes. If you are not yet familiar on how to create a pull request, [read this great guide](https://gun.io/blog/how-to-github-fork-branch-and-pull-request).
Some things that make it easier for us to accept your pull requests
@ -47,9 +89,12 @@ Some things that make it easier for us to accept your pull requests
* single-quotes
* ...
* The code is tested
* The `grunt` build passes (executes tests + linting)
* The `npm run all` build passes (executes tests + linting)
* The work is combined into a single commit
* The commit messages adhere to our [guideline](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y)
We'd be glad to assist you if you do not get these things right in the first place.
:heart: from the bpmn.io team.