CONTRIBUTING.md

Contributing Guide

Contributing to angular-translate is fairly easy. This document shows you how to get the project, run all provided tests and generate a production-ready build.

It also covers provided grunt tasks that help you develop with angular-translate.

Dependencies

To make sure that the following instructions work, please install the following dependencies on you machine:

• Node.js
• npm
• Git

If you install node through the binary installation file, npm will be already there. When npm is installed, use it to install the needed npm packages:

• bower npm install -g bower (only required when running bower manually)
• grunt-cli npm install -g grunt-cli
• karma npm install -g karma (only required when running karma manually)

Installation

To get the source of angular-translate, clone the git repository via:

$ git clone https://github.com/angular-translate/angular-translate

This will clone the complete source to your local machine. Navigate to the project folder and install all needed dependencies via npm:

$ npm install

(This will invoke a bower install automatically.)

angular-translate is now installed and ready to be built.

Building

angular-translate comes with a few grunt tasks that help you to automate the development process. The following grunt tasks are provided:

grunt

Running grunt without any parameters will actually execute the registered default task. This task is running both a lint task and a test task. Both tasks make sure your JavaScript is written well.

grunt test

grunt test executes (as you might think) the unit tests, which are located in test/unit. The task uses karma, the spectacular test runner, to execute the tests with the jasmine testing framework.

grunt build

You only have to use this task if you want to generate a production-ready build of angular-translate. This task will also lint, test and minify the source. After running this task, you'll find the following files in a generated dist folder:

dist/angular-translate-x.x.x.js
dist/angular-translate-x.x.x.min.js

grunt watch

This task will watch all relevant files. When it notices a change, it'll run the lint and test tasks. Use this task while developing on the source to make sure that every time you make a change, you get notified if your code is inconsistent or doesn't pass the tests.

grunt dev

This task extends watch. In addition, it will lint, test and copy the result into demo/. After this, just like watch, it will run these steps every time a file has changed. On top of that, this task supports live reloading (on default port).

This task works in harmony with npm run start-demo.

npm run start-demo

This task provides a simple http server on port 3005. If you start it on your machine, you have access to the project`s demos with real XHR operations.

Example: http://localhost:3005/demo/async-loader/index.html

Under the hood, we use a complete Express server stack. You will find the server configuration at server.js and additional routes for our demos at demo/server_routes.js.

Contributing/Submitting changes

• Check out a new branch based on canary and name it to what you intend to do:
  • Example:

    $ git checkout -b BRANCH_NAME origin/canary
    

    If you get an error, you may need to fetch canary first by using

    $ git remote update && git fetch
    

  • Use one branch per fix/feature
• Make your changes
  • Make sure to provide a spec for unit tests.
  • Run your tests with either karma start or grunt test.
  • In order to verify everything will work in the other test scopes (different AngularJS version), please run npm run test-scopes. If you are getting a dependency resolution issue, run npm run clean-test-scopes and try again.
  • When all tests pass, everything's fine.
• Commit your changes
  • Please provide a git message that explains what you've done.
  • ngTranslate uses Brian's conventional-changelog task, so please make sure your commits follow the conventions
  • Commit to the forked repository.
• Make a pull request
  • Make sure you send the PR to the canary branch.
  • Travis CI is watching you!

If you follow these instructions, your PR will land pretty safely in the main repo!