You can quickly set up a Vagrant-based development environment by cloning the otm-vagrant repository.
We use Github Issues to track all the work we do on OpenTreeMap and we use labels to help organize and prioritize our efforts. The contributing label is a good place to start. The OpenTreeMap core team assigns this label to issues that we identify as good candidates for new contributors.
| Label | What It Means |
|---|---|
| contributing | The issue describes a bug or enhancement that the OpenTreeMap team has identified as a good candidate for new new contributors. |
| bug | The issue describes a defect. The application does not behave as expected. |
| enhancement | The issue describes a new feature, or an improvement to an existing feature. |
| high, medium, low | These are mutually exclusive labels that identify the priority of the issue set by the OpenTreeMap core team. |
| blocked | A problem or dependency is preventing the issue from being worked on. |
| question | More discussion is needed before the issue can be worked on. |
| design | The issue primarily involves user interface design or HTML/CSS layout. |
| production | The issue describes a problem encountered on opentreemap.org |
| customer | The issue was reported by an OpenTreeMap customer. |
| +, queue, in progress, in review, tested on staging, otm release | These labels are used by the OpenTreeMap core team for work tracking. |
Members of the OpenTreeMap core team assign issues to themselves when they start working on them. Avoid working on issues that are already assigned.
Four spaces. No tabs, please.
We run all of our Python code (excluding migrations and settings) through flake8. If you are using otm-vagrant, you can use this command to run flake8:
vagrant ssh -c 'cd /vagrant/otm-core/opentreemap; flake8 --exclude migrations,opentreemap/settings/local_settings.py *'
To avoid build failures make sure to run this command against your changes before opening a pull request.
We try to unit test as much of our code as possible. If you are using otm-vagrant, this command will run the test suite:
vagrant ssh -c 'cd /vagrant/otm-core/opentreemap && ./manage.py test --noinput'
To avoid build failures please run the unit tests before submitting a pull request if you modify Python code.
OpenTreeMap uses functional views rather than class-based views and
prefers nested calls rather than decorators, to simplify testing and
composability. Read through decorators.py
file, and also the django-tinsel project and it's decorate and route functions, which we use as the foundation of our composed view
functions. For a good example of how these functions are used,
reference the treemap views module
Nearly all of the markup for OpenTreeMap is generated by Django templates, rather than client-side JavaScript. If you are going to create markup, we prefer that it is created via a Django template.
Four spaces. No tabs, please.
We use Webpack to compile nodejs-style modules for use in the browser. If you are using otm-vagrant running these commands will compile a JavaScript bundle and collect all the static Django assets.
vagrant ssh -c 'cd /vagrant/otm-core/; yarn run build; python opentreemap/manage.py collectstatic'
We use Bacon.js to manage events in the browser. Please reference the existing modules in the src directory for examples of how we use stream processing rather than directly attaching callbacks to DOM events.
We run all of our JavaScript code through jshint. If you are using otm-vagrant, you can use this command to run jshint:
vagrant ssh -c 'cd /vagrant/otm-core && yarn run check'
To avoid build failures make sure to run this command against your changes before opening a pull request if you have added or modified any JavaScript code.
We have built a mocha-based
unit test setup for our JavaScript. The
html test harness
handles finding and executing tests from any of the modules in the
test directory.
Individual tests are just functions exported from a module in the test
directory. You can open test.html to run the tests on demand, or
use testem to run the test
suite when files change.
This section addresses the question of where code should live.
Because of the complicated relationship of models associated with permission checking, permissions are centralized in a module, treemap/lib/perms.py, instead of added as methods to a class. Functions that check permissions should be written to accept a number of related types or type combinations and stored in this module. The private functions in this module should be responsible for walking the necessary relationships in order to check the permission properly.