# Contributing to Xavi

_Xavi is a completely open source project, and welcomes community contributions._

There are a number of ways to get involved:

- Report bugs via the [issue tracker](https://github.com/xavi-js/xavi/issues)
- Fix reported bugs or implement feature requests
- Write documentation and tutorials
- Writing tests and improving test coverage

### Discussion

Discussing the code and any issues will help improve the quality of the projects. Please direct any discussion to a relevant issue on the [issue tracker](https://github.com/xavi-js/xavi/issues). For more general discussion about Xavi, you can often find the core team in the [#xavi](http://webchat.freenode.net/?channels=xavi) IRC channel on chat.freenode.net.

### Getting started

Create a fork of the repository you wish to contribute to:

- [xavi](https://github.com/xavi-js/xavi) - _Server library_
- [xavi-client](https://github.com/xavi-js/xavi-client) - _Client library_
- [xavi-middleware-auth](https://github.com/xavi-js/xavi-middleware-auth) - _Authentication middleware_
- [xavi-middleware-cookie](https://github.com/xavi-js/xavi-middleware-encoding) - _Cookie middleware_
- [xavi-service-echo](https://github.com/xavi-js/xavi-service-echo) - _Echo service binding_
- [xavi-service-irc](https://github.com/xavi-js/xavi-service-irc) - _IRC service binding_
- [xavi-service-rabbitmq](https://github.com/xavi-js/xavi-service-rabbitmq) - _RabbitMQ service binding_
- [xavi-service-redis](https://github.com/xavi-js/xavi-service-redis) - _Redis service binding_
- [xavi-service-thrift](https://github.com/xavi-js/xavi-service-redis) - _Thrift service binding_
- [xavi-service-zookeeper](https://github.com/xavi-js/xavi-service-zookeeper) - _ZooKeeper service wrapper_

Clone your forked repository

```bash
$ git clone git@github.com:username/project.git && cd project
```

Add Xavi as upstream remote

```bash
$ git remote add upstream git@github.com:footballradar/project.git
```

Regularly pull changes from upstream master

```bash
$ git pull upstream master
```

Install dependencies. All projects will have various NPM dependencies.

```bash
$ npm install
```

Some projects also have Bower dependencies.

```bash
$ bower install
```

Run the Grunt "install" and "listen" tasks.

```bash
$ grunt install && grunt listen
```

_The "listen" task starts various helper services, and runs linting and testing tools after any saved changes._

You will need to have Grunt installed and available on your system PATH.

```bash
$ npm install -g grunt-cli
```

### Making changes and writing code

Locate an issue on the [issue tracker](https://github.com/xavi-js/xavi/issues) that you would like to work on. If you intend to work on something that has not been reported, please post an issue first. This will help encourage discussion about the bug or feature in question, and will make it more likely that your pull request is accepted.

Ensure that your master branch is up-to-date

```bash
$ git checkout master
$ git pull upstream master
```

Create a new branch for each bug you wish to fix or feature you wish to implement.

```bash
$ git checkout -b <BRANCH_NAME>
```

_Always write your code on a branch, not on master. If you accidentally commit to master, please reset your master branch._

```bash
$ git reset --hard upstream/master
```

Write unit tests for the bug or feature you wish to work on. Locate the relevant file in `test/specs/`. It is recommended to write failing tests first, to properly identify the desired behavior.

Next, implement the feature or bugfix you are working on.

Make sure that all unit tests pass before you commit.

```bash
$ grunt test
```

Once all the tests pass, stage and commit your changes. Break your changes into multiple commits if it makes sense.

```bash
$ git add <FILES>
$ git commit -m <COMMIT_MESSAGE>
```

Push the changes to your fork and checkout your local master branch.

```bash
$ git push -u origin <BRANCH_NAME>
$ git checkout master
```

Once you are satisifed that your changes fix a particular issue, please open a pull request on Github, and provide as much detail as possibly about the changes you have made. Once a member of the core team has approved your changes, your pull request will be merged into the master branch of that project.

### Testing your code

All Xavi projects require unit tests to cover contributed code.

Server modules use [Nodeunit](https://github.com/caolan/nodeunit); browser modules use [Jasmine](https://github.com/pivotal/jasmine) and [Istanbul](https://github.com/gotwarlost/istanbul) to measure coverage.

All projects require as high test coverage as is reasonable, and where possible this is enforced by the test runner. Please help us maintain high test coverage by providing unit tests for any code contribution. Pull requests that do not include unit tests will be rejected.