# Contributing to Grivet

Contributions are welcome! You can contribute by:

- Reporting a bug
- Proposing new features
- Discussing the current state of the code
- Submitting a pull request

## Reporting a bug

We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/muellerbbm-vas/grivet/issues).

### Write bug reports with detail, background, and sample code

Great Bug Reports tend to have:

- A quick summary and/or background
- Steps to reproduce
  - Be specific!
  - Give sample code if you can
- What you expected would happen
- What actually happens
- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

## Proposing new features

We use GitHub issues to track and discuss feature requests. Suggest a feature by [opening a new issue](https://github.com/muellerbbm-vas/grivet/issues).

## Contributing code

Contributions will be accepted to the [develop](https://github.com/muellerbbm-vas/grivet/tree/develop) branch only.

- [Fork the repo](http://help.github.com/fork-a-repo/) and create your feature branch from `develop`.
- Run `npm install` (you will need [Node.js](https://nodejs.org) installed on your system)
- Add your changes
- Read the section on commit messages below
- Mention your changes in the `Unreleased` section of the [changelog](https://github.com/muellerbbm-vas/grivet/blob/master/CHANGELOG.md)
- If you've added code that should be tested, add tests
- If you've changed APIs, update the documentation
- Ensure the test suite passes by running `npm test`
- Make sure your code passes lint by running `npm run lint`
- Push to your forked repo and issue a [pull request](http://help.github.com/send-pull-requests/)

### Commit messages

- Prefix your commit message with a category identifier:

  - `feat:` A new feature or change to existing feature
  - `fix:` A bug fix
  - `docs:` Documentation only changes
  - `test:` Adding missing tests or correcting existing tests
  - `refactor:` A code change that neither fixes a bug nor adds a feature
  - `build:` Changes that affect the build system or external dependencies
  - `perf:` A code change that improves performance
  - `style:` Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
  - `ci:` Changes to our CI configuration files and scripts

- If your change fixes an issue, add `Fixes #<number of issue>` to your commit message

### Running tests

Tests are located in the `test` subfolder and are named `*.spec.ts`.

Run tests manually:

    > npm test

Additionally, all tests are run before pushing to ensure no failing tests reach the remote repository.

### Running lint

`tslint` will be run automatically before each commit, or manually:

    > npm run lint

Additionally, if you are using Visual Studio Code, install the [tslint](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-typescript-tslint-plugin) extension.

### Use a consistent coding style

Have a look at our [.prettierrc file](https://github.com/muellerbbm-vas/grivet/blob/master/.prettierrc). This style will be applied in a git pre-commit hook.
Additionally, if you are using Visual Studio Code, install the [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extension.

### Updating the documentation

The [reference documentation](https://muellerbbm-vas.github.io/grivet/docs/index.html) is hosted on GitHub pages and always serves the `docs` folder of the `gh-pages` branch. The `docs` folder is generated by the [CI server](https://travis-ci.org/muellerbbm-vas/grivet) by running `typedoc` over all `src` files in the `master` branch and pushing the result to the `gh-pages` branch.

So, keeping the JSDoc-style comments in the source code nice and up to date is important, as they will appear on the public reference documentation :)

You generate the documentation locally by running

    > npm run docs

### Any contributions you make will be under the MIT Software License

In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.

## For maintainers

### Creating a new release

- Make sure you are on an up to date `develop` branch.
- Check that the changelog reflects all user-visible changes and fixes
- Update the changelog by moving everything from the `Unreleased` section to a new section named `<new version> - <date>`
- Run `npm version <new version>`. This updates the version in `package.json` and creates a tagged commit.
- Push the `develop` branch
- Create a pull request to `master` and wait for all tests and checks to succeed
- Accept and merge the PR (do not delete the `develop` branch afterwards, even if GitHub suggests it ;)
- Merge `master` back into `develop`
- Run `npm login` and `npm publish` to publish the package
- Go to the [releases](https://github.com/muellerbbm-vas/grivet/releases) page and draft a new release (based on the new version tag), mentioning the changes from the changelog

## License

By contributing, you agree that your contributions will be licensed under its MIT License.
