Permalink
Browse files

Initial contributor proposal #3185

I've re-written some of the contributor file to try and cover some of the changes to our process.
  • Loading branch information...
1 parent 828a5cc commit b910a0065edb60c7a4295df6babff610ecb5486a @scott-w scott-w committed Sep 17, 2016
Showing with 58 additions and 55 deletions.
  1. +58 −55 CONTRIBUTING.md
View
@@ -3,29 +3,24 @@ the process of getting changes merged in and released.
1. [Setting up Marionette locally](#setting-up-marionette-locally)
2. [Reporting a bug](#reporting-a-bug)
- 1. [When you have a patch](#when-you-have-a-patch)
- 2. [When you don't have a bug fix](#when-you-dont-have-a-bug-fix)
-3. [Running Tests](#running-tests)
-4. [Updating docs](#updating-docs)
+3. [Submitting patches and fixes](#submitting-patches-and-fixes)
+4. [Running Tests](#running-tests)
## Setting up Marionette locally
* Fork the Marionette repo.
-
* `git clone` your fork onto your computer.
-
* Run `npm install` to make sure you have all Marionette dependencies locally.
-
* Run `npm run build` to build source files.
## Reporting a bug
In order to best help out with bugs, we need to know the following information
in your bug submission:
-* Marionette version no.
-* Backbone version no.
+* Marionette version #.
+* Backbone version #.
Including this information in a submission will help us test the problem and
ensure that the bug is both reproduced and corrected on the platforms /
@@ -56,72 +51,80 @@ Please refrain from giving code examples in altJS languages like CoffeeScript,
etc. Marionette is written in plain-old JavaScript and is generally easier for all
members in the community to read.
-### When you have a patch
+### When you don't have a bug fix
+
+If you are stuck in a scenario that fails in your app, but you don't know how to
+fix it, submit a failing spec to show the failing scenario. Follow the
+guidelines for a pull request submission, but don't worry about fixing the
+problem. A failing spec to show that a problem exists is a very very very
+helpful pull request for us.
+
+We'll even accept a failing test pasted into the ticket description instead of a
+PR. That would at least get us started on creating the failing test in the code.
+
+## Submitting patches and fixes
See [Github's documentation for pull
requests](https://help.github.com/articles/using-pull-requests).
-Pull requests are by far the best way to contribute to Marionette. Any time you
-can send us a pull request with the changes that you want, we will have an
-easier time seeing what you are trying to do. But a pull request in itself is
-not usually sufficient. There needs to be some context and purpose with it, and
-it should be done against a specific branch.
+Pull requests are by far the best way to contribute to Marionette. They are by
+far the easiest way to demonstrate issues and your proposed resolution. To
+really help us evaluate your pull request and bring it into Marionette, please
+provide as much information as possible and follow the guidelines below:
-Try and stick to Marionette's existing coding conventions (just use the file
-you're editing as a guideline). Installing the appropriate [EditorConfig
-plugin](http://editorconfig.org/#download) for your code editor will help with
-this.
+1. Determine the branch as your base: `next` or `master`
+2. Provide a brief summary of what your pull request is doing
+3. Reference any relevant Github issue numbers
+4. Include any extra detail you feel will help provide context
-* Decide whether you are need to base off of `next` or `patch` branch. Do not
- base off `master`.
+### Determining your branch
- * PRs for all bug fixes, doc updates, and unit tests of existing features
-should be opened against `patch`.
+When submitting your pull request, you need to determine whether to base off
+`next` or `master`:
- * PRs for all new features, breaking or not, should be opened against
-`next`.
+* If you're submitting a bug fix, base off `next`
+* If you're submitting a new feature, base off `next`
+* If you're submitting documentation for a new feature, base off `next`
+* If you're submitting documentation for the current release, base off `master`
-* Checkout `next` or `patch` and run `git pull` to make sure it is updated.
+### Submitting a Great Patch
-* Create a new branch for your PR by running `git checkout -b new-branch-name`
+We want Marionette to provide a great experience to developers and help you
+write great applications using it. To help us achieve this goal, please follow
+these guidelines when submitting your patches.
-* Whenever possible, submit the specs (unit tests) that correspond to your pull
-request.
+#### Solving Issues
-* Make changes to files in `src`, not the builds in `lib`. This is built before
-every release.
+When you're submitting a bug fix, include spec tests, where applicable, showing
+the issue and the resolution. We strive to maintain 100% code coverage in our
+testing.
-* Push to your remote fork then compare.
+#### Coding Guidelines
-* Submit pull request.
- When doing so, make sure you follow the format for description outlined
-[above](#format-desc).
- If you are resolving an existing issue, make sure to link to the issue in the
-description.
+The Marionette coding conventions are provided in the ESLint configuration
+included in the repository. Most IDEs and text editors will provide, or allow
+for, a plugin for ESLint to read the `.eslintrc` file.
+For areas where the configuration provides no guidance, try to stick to the
+conventions in the file you're editing.
-### When you don't have a bug fix
+#### How we Approve Pull Requests
-If you are stuck in a scenario that fails in your app, but you don't know how to
-fix it, submit a failing spec to show the failing scenario. Follow the
-guidelines for a pull request submission, but don't worry about fixing the
-problem. A failing spec to show that a problem exists is a very very very
-helpful pull request for us.
+We utilise Github's review approach. When receiving your pull request, we will
+comment inline and provide guidance to help you get your pull request merged
+into Marionette. This is not a one-way process and we're more than happy to
+discuss the context of your decisions.
-We'll even accept a failing test pasted into the ticket description instead of a
-PR. That would at least get us started on creating the failing test in the code.
+Once two Marionette.js members approve the pull request, we will then merge it
+into the base branch.
+
+Please remember that Marionette is a community-maintained project and, as such,
+many of us are working on this in our spare time. If we haven't commented on
+your pull request, please be patient. We may be available on our Gitter channel
+to discuss further.
## Running Tests
* via command-line by running `npm test`
-
* in the browser by running `npm run test-browser`
-To see test matrix - run `npm run coverage`
-
-## Updating docs
-
-If you notice any problems with any documentation, please fix it and we'll get
-it merged as soon as we can. For small things like typos and grammar, just click
-the "Edit this file" button and send in the pull request for the fix. For larger
-documentation changes, a regular pull request as outlined above is more
-appropriate.
+To see the test matrix - run `npm run coverage`

0 comments on commit b910a00

Please sign in to comment.