Contributing

License

Angular is an open source project licensed under the MIT license. Your contributions are always welcome. When working with angular source base, please follow the guidelines provided on this page.

Contributing to Source Code

We'd love for you to contribute to our source code and to make angular even better than it is today! Here are the guidelines we'd like you to use:

Applying Code Standards

To ensure consistency throughout the source code, keep these rules in mind as you are working:

Checking Out and Building Angular

The angular source code is hosted at Github, which we also use to accept code contributions. Several steps are needed to check out and build angular:

Installation Dependencies

Before you can build angular, you must install or configure the following dependencies on your machine:

Creating a Github Account and Forking Angular

To create a Github account, follow the instructions here. Afterwards, go ahead and fork the main angular repository.

Building Angular

To build angular, you check out the source code and use Rake to generate the non-minified and minified angular files:

  1. To clone your Github repository, run:

    git clone git@github.com:<github username>/angular.js.git
    
  2. To go to the angular directory, run:

    cd angular.js
    
  3. To add the main angular repository as an upstream remote to your repository, run:

    git remote add upstream https://github.com/angular/angular.js.git
    
  4. To build angular, run:

    rake package
    

The build output can be located under the build directory. It consists of the following files and directories:

Running a Local Development Web Server

To debug or test code, it is often useful to have a local HTTP server. For this purpose, we have made available a local web server based on Node.js.

  1. To start the web server, run:

    ./nodeserver.sh
    
  2. To access the local server, go to this website:

    http://localhost:8000/
    

    By default, it serves the contents of the angular project directory.

Running the Unit Test Suite

Our unit and integration tests are written with Jasmine and executed with JsTestDriver. To run the tests:

  1. To start the JSTD server, run:

    ./server.sh
    
  2. To capture one or more browsers, go to this website:

    http://localhost:9876/
    
  3. To trigger a test execution, run:

    ./test.sh
    
  4. To automatically run the test suite each time one or more of the files in the project directory is changed, you can install watchr and then run:

    watchr watchr.rb
    
  5. To view the output of each test run, you can tail this log file:

    ./logs/jstd.log
    

Running the End2End Test Suite

To run the End2End test suite:

  1. Start the local web server.
  2. In a browser, go to:

    http://localhost:8000/build/docs/docs-scenario.html
    

    The tests are executed automatically.

Submitting Your Changes

To create and submit a change:

  1. Create a new branch off the master for your changes:

    git branch my-fix-branch
    
  2. Check out the branch:

    git checkout my-fix-branch
    
  3. Create your patch, make sure to have plenty of tests (that pass).

  4. Commit your changes:

    git commit -a
    
  5. Run JavaScript Lint and be sure to address all new warnings and errors:

    rake lint
    
  6. Push your branch to Github:

    git push origin my-fix-branch
    
  7. In Github, send a pull request to angular:master.

  8. When the patch is reviewed and merged, delete your branch and pull yours — and other — changes from the main (upstream) repository:

    1. To delete the branch in Github, run:

      git push origin :my-fix-branch
      
    2. To check out the master branch, run:

      git checkout master
      
    3. To delete a local branch, run:

      git branch -D my-fix-branch
      
    4. To update your master with the latest upstream version, run:

      git pull --ff upstream master
      

That's it! Thank you for your contribution!