diff --git a/Contribute.markdown b/Contribute.markdown index e04f4b65..11ca32d2 100644 --- a/Contribute.markdown +++ b/Contribute.markdown @@ -1,7 +1,5 @@ # Developing for Jasmine Core -## How to Contribute - We welcome your contributions - Thanks for helping make Jasmine a better project for everyone. Please review the backlog and discussion lists (the main group - [http://groups.google.com/group/jasmine-js](http://groups.google.com/group/jasmine-js) and the developer's list - [http://groups.google.com/group/jasmine-js-dev](http://groups.google.com/group/jasmine-js-dev)) before starting work - what you're looking for may already have been done. If it hasn't, the community can help make your contribution better. ## General Workflow @@ -14,7 +12,49 @@ Please submit pull requests via feature branches using the semi-standard workflo 1. Push to the branch (`git push origin my-new-feature`) 1. Create new Pull Request -## Install Dependencies +We favor pull requests with very small, single commits with a single purpose. + +## Background + +### Directory Structure + +* `/src` contains all of the source files + * `/src/console` - Node.js-specific files + * `/src/core` - generic source files + * `/src/html` - browser-specific files +* `/spec` contains all of the tests + * mirrors the source directory + * there are some additional files +* `/dist` contains the standalone distributions as zip files +* `/lib` contains the generated files for distribution as the Jasmine Rubygem and the Python package + +### Self-testing + +Note that Jasmine tests itself. The files in `lib` are loaded first, defining the reference `jasmine`. Then the files in `src` are loaded, defining the reference `j$`. So there are two copies of the code loaded under test. + +The tests should always use `j$` to refer to the objects and functions that are being tested. But the tests can use functions on `jasmine` as needed. _Be careful how you structure any new test code_. Copy the patterns you see in the existing code - this ensures that the code you're testing is not leaking into the `jasmine` reference and vice-versa. + +### `boot.js` + +__This is new for Jasmine 2.0.__ + +This file does all of the setup necessary for Jasmine to work. It loads all of the code, creates an `Env`, attaches the global functions, and builds the reporter. It also sets up the execution of the `Env` - for browsers this is in `window.onload`. While the default in `lib` is appropriate for browsers, projects may wish to customize this file. + +For example, for Jasmine development there is a different `dev_boot.js` for Jasmine development that does more work. + +### Compatibility + +* Browser Minimum + * IE8 + * Firefox 3.x + * Chrome ?? + * Safari 5 + +## Development + +All source code belongs in `src/`. The `core/` directory contains the bulk of Jasmine's functionality. This code should remain browser- and environment-agnostic. If your feature or fix cannot be, as mentioned above, please degrade gracefully. Any code that should only be in a non-browser environment should live in `src/console/`. Any code that depends on a browser (specifically, it expects `window` to be the global or `document` is present) should live in `src/html/`. + +### Install Dependencies Jasmine Core relies on Ruby and Node.js. @@ -34,7 +74,7 @@ To install the Node dependencies, you will need Node.js, Npm, and [Grunt](http:/ ...you see that JSHint runs your system is ready. -## How to write new Jasmine code +### How to write new Jasmine code Or, How to make a successful pull request @@ -47,11 +87,7 @@ Or, How to make a successful pull request Follow these tips and your pull request, patch, or suggestion is much more likely to be integrated. -## Development - -All source code belongs in `src/`. The `core/` directory contains the bulk of Jasmine's functionality. This code should remain browser- and environment-agnostic. If your feature or fix cannot be, as mentioned above, please degrade gracefully. Any code that should only be in a non-browser environment should live in `src/console/`. Any code that depends on a browser (specifically, it expects `window` to be the global or `document` is present) should live in `src/html/`. - -## Running Specs +### Running Specs Jasmine uses the [Jasmine Ruby gem](http://github.com/pivotal/jasmine-gem) to test itself in browser. @@ -71,4 +107,5 @@ Jasmine uses Node.js with a custom runner to test outside of a browser. 1. Ensure JSHint is green with `grunt jsHint` 1. Build `jasmine.js` with `grunt buildDistribution` and run all specs again - this ensures that your changes self-test well +Note that we use Travis for Continuous Integration. We only accept green pull requests.