| 1 | # Contributing
|
| 2 |
|
| 3 | Thanks for your interest in contributing! The advice below will help you get your issue fixed / pull request merged.
|
| 4 |
|
| 5 |
|
| 6 | ## Purpose
|
| 7 |
|
| 8 | Nunjucks has the following purpose:
|
| 9 |
|
| 10 | * Aim for templating feature parity with Jinja2.
|
| 11 | * Aim for templating feature parity with Twig, but only when not conflicting with Jinja2 parity.
|
| 12 | * Works in all node releases that are
|
| 13 | [actively maintained by the Node Foundation](https://github.com/nodejs/Release#release-schedule)
|
| 14 | * Works in all modern browsers (with [ES5 support](http://kangax.github.io/compat-table/es5/)).
|
| 15 | * Works in IE8 with [es5-shim](https://github.com/es-shims/es5-shim).
|
| 16 | * Keep footprint browser files as small as possible (save on bandwidth, download time).
|
| 17 | * Keep performance as fast as possible (see benchmarks).
|
| 18 | * Keep maintenance as easy as possible (avoid complexity, automate what we can).
|
| 19 |
|
| 20 | Notes:
|
| 21 |
|
| 22 | * We don't aim for parity of all language specific syntax.
|
| 23 | * We don't aim for parity of language specific filters like [Twig's PHP date format](http://twig.sensiolabs.org/doc/functions/date.html).
|
| 24 |
|
| 25 | Issues and pull requests contributing to this purpose have the best chance to make it into Nunjucks.
|
| 26 |
|
| 27 |
|
| 28 | ## Questions?
|
| 29 |
|
| 30 | Please DO NOT ask "how do I?" or usage questions via GitHub issues. Instead,
|
| 31 | use the [https://groups.google.com/forum/#!forum/nunjucks](mailing list).
|
| 32 |
|
| 33 |
|
| 34 | ## Submitting Issues
|
| 35 |
|
| 36 | Issues are easier to reproduce/resolve when they have:
|
| 37 |
|
| 38 | - A pull request with a failing test demonstrating the issue
|
| 39 | - A code example that produces the issue consistently
|
| 40 | - A traceback (when applicable)
|
| 41 |
|
| 42 |
|
| 43 | ## Pull Requests
|
| 44 |
|
| 45 | When creating a pull request:
|
| 46 |
|
| 47 | - Write tests (see below).
|
| 48 | - Note user-facing changes in the [`CHANGELOG.md`](CHANGELOG.md) file.
|
| 49 | - Update the documentation (in [`docs/`](docs/)) as needed.
|
| 50 |
|
| 51 |
|
| 52 | ## Testing
|
| 53 |
|
| 54 | Please add tests for any changes you submit. The tests should fail before your
|
| 55 | code changes, and pass with your changes. Existing tests should not break. Test
|
| 56 | coverage (output at the end of every test run) should never decrease after your
|
| 57 | changes.
|
| 58 |
|
| 59 | To install all the requirements for running the tests:
|
| 60 |
|
| 61 | ```bash
|
| 62 | npm install
|
| 63 | ```
|
| 64 |
|
| 65 | To run the tests:
|
| 66 |
|
| 67 | ```bash
|
| 68 | npm test
|
| 69 | ```
|