Skip to content

Latest commit

 

History

History
162 lines (118 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

162 lines (118 loc) · 6.32 KB
Raw

Contributing to Mockjax

First of all, thank you for helping make Mockjax the best plugin it can be! We truly appreciate the support. Before you submit that Pull Request, please be sure to follow these guidelines.

Key Points

  • Write small, atomic commits with good messages
  • Writes tests (for both passing and failing conditions)
  • Run the tests (grunt test, but also in various browsers)
  • Generate a distribution build (grunt build)
  • Write a good PR!

Accurately describe your code submission

Be sure to identify everything that is within your pull request in the description. If you have code that fixes a bug and also cleans up some documentation, please specify both! Additionally, if your PR fixes or resolves a specific Github issue please reference it using the #[id] format so that the two can be linked!

Commit messages

Just as with the PR description, your commit messages should clearly identify what was included in that commit. Keep them short and sweet so we can just scan the titles of the commit and dig deeper if we need to.

Smaller commits

Along the same line, we would prefer to see different aspects of your PR in separate commits versus one big commit. So if you are submitting a PR that fixes a bug, updates the documentation, and cleans up some whitespace, please place all three of those things in separate commits! This allows us to roll back specific work if need be without destroying the entire contribution.

Try to keep the style consistent

As much as possible we need to try to keep the coding style consistent within the plugin. That means using the same indentation style, quotes, spacing, etc. Please try to keep your work in line with what is already in the library already, but feel free to ping someone in the Github issues if you have any questions about coding style generally.

Add tests!

We really need to see tests for any commit other than documentation. If you are fixing a bug add a breaking test first, then the code that fixes that test. If you are developing a new feature, add complete tests for the feature. That includes tests for success cases as well as failure cases!

We use QUnit as our testing tool of choice, so please write them using that API. For now you can simply add them to the /test/test.js file. There are modules in there, so try to add the tests in a logical location.

RUN THE TESTS

Due to the need to load some of the proxy files asynchronously, you'll need to view the test files over HTTP. You can do some initial testing with Chrome headless using the Grunt task, but you should also test in (multiple) browsers!

To run from Grunt...

Simply run:

~$ grunt test

Note that this will run all tests for all supported versions of jQuery!

Want to run just a subset of the tests? And maybe only a certain jQuery version? Try this:

~$ grunt test:version:3.2.1:core,namespace,bugs

The command above will run the "core", "namespace", and "bugs" test modules against jQuery version 3.2.1 only.

You could also run something like the command below to test all supported jQuery versions, but only certain test modules:

~$ grunt test:all:core,namespace,bugs

To run in a browser...

You should be able to run a small local server:

Node:

~$ npm install -g http-server
~$ cd /path/to/mockjax
mockjax/$ http-server -p 8080

Python:

~$ cd /path/to/mockjax
mockjax/$ python -m SimpleHTTPServer 8080

PHP (5.4+):

~$ cd /path/to/mockjax
mockjax/$ php -S localhost:8080

Then just visit http://localhost:8080/test/index.html in the browser! Once there, be sure to click through each of the jQuery versions in the header to run the tests against each version. (If you have trouble running in different versions, make sure you are viewing /test/index.html not just /test/ .)

Run your tests everywhere

Lastly, we'd like you to run your tests on as many browsers as possible. Check the main README file for the browsers we support.

We highly recommend running your tests in a virtual environment to capture any issues in specific browsers. You can do so easily with out BrowserStack integration. In fact, all of our tests will run on BrowserStack's platform for all supported browsers when you submit a PR to master. That said, you can run these on your own using the command below. All you need to do is set the BROWSERSTACK_KEY environment variable first! Now run this in your terminal:

~$ node browserstack.js

Be sure to generate a build!

Running the default grunt task will only lint and test the files, it does not produce a distribution as that isn't necessary most of the time. Instead, you should generate a new set of "dist" files before submitting your PR. To do this, just run grunt build

Submit Your PR

This is the last step! First, be sure you're merging with the correct branch! Version 2.x of Mockjax is on the master branch, but if you're submitting a bug fix for v1.x, make sure it is submitted to the v1.x branch as well as master (if the bug exists in both).

You should also write a good PR message with information on why this feature or fix is necessary or a good idea. For features, be sure to include information on how to use the feature; and for bugs, information on how to reproduce the bug is helpful!

Publishing a Release

Although individual contributors cannot publish a release, it's good to have documentation on what goes into that in case anyone needs to take over the process. Currently, @jakerella is the only one doing so.

  1. Create a branch for the release (usually with the proposed version number in the name)
  2. Ensure that all tests are passing in all supported browsers that you can (see below).
  3. Update the CHANGELOG.md, package.json version, and any other necessary files. (Note that these can be in a commit, but put them in that new branch.)
  4. Make sure to generate fresh dist files if necessary and commit those.
  5. Submit a PR for the branch, this will initiate the Travis CI checks.
  6. Ask others for input on the PR (mostly testing in their own browsers).
  7. If all is well, merge the branch into master
  8. Create a release on Github with a tag matching the version number and proper info.
  9. Run npm publish on master to push the new version up to npm.