github.com/yrj2011/jx-test-infra@v0.0.0-20190529031832-7a2065ee98eb/triage/node_modules/jasmine-core/.github/CONTRIBUTING.md (about)

     1  # Developing for Jasmine Core
     2  
     3  We welcome your contributions! Thanks for helping make Jasmine a better project for everyone. Please review the backlog and discussion lists 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. If you want to contribute but don't know what to work on, [issues tagged ready for work](https://github.com/jasmine/jasmine/labels/ready%20for%20work) should have enough detail to get started.
     4  
     5  ## Links
     6  
     7  - [Jasmine Google Group](http://groups.google.com/group/jasmine-js)
     8  - [Jasmine-dev Google Group](http://groups.google.com/group/jasmine-js-dev)
     9  - [Jasmine on PivotalTracker](https://www.pivotaltracker.com/n/projects/10606)
    10  
    11  ## General Workflow
    12  
    13  Please submit pull requests via feature branches using the semi-standard workflow of:
    14  
    15  ```bash
    16  git clone git@github.com:yourUserName/jasmine.git              # Clone your fork
    17  cd jasmine                                                     # Change directory
    18  git remote add upstream https://github.com/jasmine/jasmine.git # Assign original repository to a remote named 'upstream'
    19  git fetch upstream                                             # Pull in changes not present in your local repository
    20  git checkout -b my-new-feature                                 # Create your feature branch
    21  git commit -am 'Add some feature'                              # Commit your changes
    22  git push origin my-new-feature                                 # Push to the branch
    23  ```
    24  
    25  Once you've pushed a feature branch to your forked repo, you're ready to open a pull request. We favor pull requests with very small, single commits with a single purpose.
    26  
    27  ## Background
    28  
    29  ### Directory Structure
    30  
    31  * `/src` contains all of the source files
    32      * `/src/console` - Node.js-specific files
    33      * `/src/core` - generic source files
    34      * `/src/html` - browser-specific files
    35  * `/spec` contains all of the tests
    36      * mirrors the source directory
    37      * there are some additional files
    38  * `/dist` contains the standalone distributions as zip files
    39  * `/lib` contains the generated files for distribution as the Jasmine Rubygem and the Python package
    40  
    41  ### Self-testing
    42  
    43  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.
    44  
    45  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.
    46  
    47  ### `boot.js`
    48  
    49  __This is new for Jasmine 2.0.__
    50  
    51  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.
    52  
    53  For example, for Jasmine development there is a different `dev_boot.js` for Jasmine development that does more work.
    54  
    55  ### Compatibility
    56  
    57  * Browser Minimum
    58    * IE8
    59    * Firefox 3.x
    60    * Chrome ??
    61    * Safari 5
    62  
    63  ## Development
    64  
    65  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/`.
    66  
    67  ### Install Dependencies
    68  
    69  Jasmine Core relies on Ruby and Node.js.
    70  
    71  To install the Ruby dependencies, you will need Ruby, Rubygems, and Bundler available. Then:
    72  
    73      $ bundle
    74  
    75  ...will install all of the Ruby dependencies. If the ffi gem fails to build its native extensions, you may need to manually install some system dependencies. On Ubuntu:
    76  
    77      $ apt-get install gcc ruby ruby-dev libxml2 libxml2-dev libxslt1-dev
    78  
    79  ...should get you to the point that `bundle` can install everything.
    80  
    81  To install the Node dependencies, you will need Node.js, Npm, and [Grunt](http://gruntjs.com/), the [grunt-cli](https://github.com/gruntjs/grunt-cli) and ensure that `grunt` is on your path.
    82  
    83      $ npm install --local
    84  
    85  ...will install all of the node modules locally. Now run
    86  
    87      $ grunt
    88  
    89  ...if you see that JSHint runs, your system is ready.
    90  
    91  ### How to write new Jasmine code
    92  
    93  Or, How to make a successful pull request
    94  
    95  * _Do not change the public interface_. Lots of projects depend on Jasmine and if you aren't careful you'll break them
    96  * _Be environment agnostic_ - server-side developers are just as important as browser developers
    97  * _Be browser agnostic_ - if you must rely on browser-specific functionality, please write it in a way that degrades gracefully
    98  * _Write specs_ - Jasmine's a testing framework; don't add functionality without test-driving it
    99  * _Write code in the style of the rest of the repo_ - Jasmine should look like a cohesive whole
   100  * _Ensure the *entire* test suite is green_ in all the big browsers, Node, and JSHint - your contribution shouldn't break Jasmine for other users
   101  
   102  Follow these tips and your pull request, patch, or suggestion is much more likely to be integrated.
   103  
   104  ### Running Specs
   105  
   106  Jasmine uses the [Jasmine Ruby gem](http://github.com/jasmine/jasmine-gem) to test itself in browser.
   107  
   108      $ bundle exec rake jasmine
   109  
   110  ...and then visit `http://localhost:8888` to run specs.
   111  
   112  Jasmine uses the [Jasmine NPM package](http://github.com/jasmine/jasmine-npm) to test itself in a Node.js/npm environment.
   113  
   114      $ grunt execSpecsInNode
   115  
   116  ...and then the results will print to the console. All specs run except those that expect a browser (the specs in `spec/html` are ignored).
   117  
   118  The easiest way to run the tests in **Internet Explorer** is to run a VM that has IE installed. It's easy to do this with VirtualBox.
   119  
   120  1. Download and install [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
   121  1. Download a VM image [from Microsoft](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/). Select "VirtualBox" as the platform.
   122  1. Unzip the downloaded archive. There should be an OVA file inside.
   123  1. In VirtualBox, choose `File > Import Appliance` and select the OVA file. Accept the default settings in the dialog that appears. Now you have a Windows VM!
   124  1. Run the VM and start IE.
   125  1. With `bundle exec rake jasmine` running on your host machine, navigate to `http://10.0.2.2:8888` in IE.
   126  
   127  ## Before Committing or Submitting a Pull Request
   128  
   129  1. Ensure all specs are green in browser *and* node
   130  1. Ensure JSHint is green with `grunt jshint`
   131  1. Build `jasmine.js` with `grunt buildDistribution` and run all specs again - this ensures that your changes self-test well
   132  
   133  ## Submitting a Pull Request
   134  1. Revert your changes to `jasmine.js` and `jasmine-html.js`
   135    * We do this because `jasmine.js` and `jasmine-html.js` are auto-generated (as you've seen in the previous steps) and accepting multiple pull requests when this auto-generated file changes causes lots of headaches
   136  1. When we accept your pull request, we will generate these files as a separate commit and merge the entire branch into master
   137  
   138  Note that we use Travis for Continuous Integration. We only accept green pull requests.
   139