Permalink
Browse files

Document purpose (#851)

* Add "project purpose" to contribution guidelines

Resolves #837

* Link to "contribution guidelines" from main readme
  • Loading branch information...
1 parent a2b73b5 commit abda2e2034ee2684aba3dd2c4543fd9187f0cdd5 @jbmoelker jbmoelker committed on GitHub Sep 24, 2016
Showing with 42 additions and 20 deletions.
  1. +37 −17 CONTRIBUTING.md
  2. +5 −3 README.md
View
@@ -1,18 +1,36 @@
-Contributing
-============
+# Contributing
-Thanks for your interest in contributing! The advice below will help you get
-your issue fixed / pull request merged.
+Thanks for your interest in contributing! The advice below will help you get your issue fixed / pull request merged.
-Please file bugs and send pull requests to the
-[GitHub repository](https://github.com/mozilla/nunjucks/) and
-[issue tracker](https://github.com/mozilla/nunjucks/issues).
+
+## Purpose
+
+Nunjucks has the following purpose:
+
+* Aim for templating feature parity with Jinja2.
+* Aim for templating feature parity with Twig, but only when not conflicting with Jinja2 parity.
+* Works in Node >= v0.10 (as defined in [Travis test matrix]).(https://github.com/mozilla/nunjucks/blob/master/.travis.yml#L9).
+* Works in all modern browsers (with [ES5 support](http://kangax.github.io/compat-table/es5/)).
+* Works in IE8 with [es5-shim](https://github.com/es-shims/es5-shim).
+* Keep footprint browser files as small as possible (save on bandwidth, download time).
+* Keep performance as fast as possible (see benchmarks).
+* Keep maintenance as easy as possible (avoid complexity, automate what we can).
+
+Notes:
+
+* We don't aim for parity of language specific syntax like Python's splice notation `{{ foo[start:end:step] }}`.
+* We don't aim for parity of language specific filters like [Twig's PHP date format](http://twig.sensiolabs.org/doc/functions/date.html).
+
+Issues and pull requests contributing to this purpose have the best chance to make it into Nunjucks.
+
+
+## Questions?
Please DO NOT ask "how do I?" or usage questions via GitHub issues. Instead,
use the [https://groups.google.com/forum/#!forum/nunjucks](mailing list).
-Submitting Issues
------------------
+
+## Submitting Issues
Issues are easier to reproduce/resolve when they have:
@@ -21,18 +39,16 @@ Issues are easier to reproduce/resolve when they have:
- A traceback (when applicable)
-Pull Requests
--------------
+## Pull Requests
When creating a pull request:
- Write tests (see below).
-- Note user-facing changes in the `CHANGELOG.md` file.
-- Update the documentation (in `docs/`) as needed.
+- Note user-facing changes in the [`CHANGELOG.md`](CHANGELOG.md) file.
+- Update the documentation (in [`docs/`](docs/)) as needed.
-Testing
--------
+## Testing
Please add tests for any changes you submit. The tests should fail before your
code changes, and pass with your changes. Existing tests should not break. Test
@@ -41,8 +57,12 @@ changes.
To install all the requirements for running the tests:
- npm install
+```bash
+npm install
+```
To run the tests:
- npm test
+```bash
+npm test
+```
View
@@ -23,13 +23,15 @@ Supported in all modern browsers. For IE8 support, use [es5-shim](https://github
Run the tests with `npm test`.
-Watch `master` branch's tests running at http://mozilla.github.io/nunjucks/files/tests/browser/.
+Watch `master` branch's [tests running in the browser](https://mozilla.github.io/nunjucks/files/tests/browser/).
## Mailing List
Join our mailing list and get help with and issues you have:
https://groups.google.com/forum/?fromgroups#!forum/nunjucks
-## Contributors
+## Want to help?
-https://github.com/mozilla/nunjucks/graphs/contributors
+Contributions are always welcome! Before you submit an issue or pull request, please read our [contribution guidelines](CONTRIBUTING.md).
+
+[Contributors](https://github.com/mozilla/nunjucks/graphs/contributors)

0 comments on commit abda2e2

Please sign in to comment.