cartodb/CONTRIBUTING.md

The development tracker for CartoDB is on GitHub: http://github.com/cartodb/cartodb

Bug fixes are best reported as pull requests over there. Features are best discussed on the mailing list: https://groups.google.com/d/forum/cartodb

---

1. General
2. Documentation
3. Frontend
4. Submitting contributions

---

General

Every new feature (as well as bugfixes) should come with a test case. Depending on context different guidelines might apply, see following sections.

Unless you plan to develop frontend code you can serve assets from our CDN instead, make sure the following is set in the config/app_config.yml:

app_assets:

  asset_host: '//cartodb-libs.global.ssl.fastly.net/cartodbui'

Don't forget to restart Rails after you have modified config/app_config.yml.

Documentation

Documentation that don't fit well inline (e.g. high-level stuff) should be placed in the /doc directory.

Frontend

The frontend is really standalone code, but is integrated with/served by the Rails application.

CSS

We use SASS, with .scss format, which are located at app/assets/stylesheets. Grunt is used to compile the files into .css files, instead of the default Sprockets pipeline that Rails provide.

See doc/frontend/README.md for more in-depth documentation.

Also CartoDB makes use of a linter machine for checking possible errors in those stylesheets. Rules are specified in the scss-style.yml file. Once a new Pull Request is started, Hound application will check those SCSS changes for warnings.

JS

CartoDB is built on top of CartoDB.js, which in turns depends on some common libraries, in particular worth mentioning:

• BackboneJS 0.9.2.
• jQuery 1.7.2
• underscore.js 1.4.4

Source code is located at lib/assets/javascripts, dependencies at vendor/assets/javascripts.

See doc/frontend/README.md for more in-depth documentation.

Until our guidelines are publically available follow the existing file/directory and style structure.

Update CartoDB.js

Follow these steps to update to get latest changes:

• go to lib/assets/javascripts/cdb/
• git checkout develop && git pull
• go back to root and run grunt cdb
• commit both the new revision of the submodule and the generated file vendor/assets/javascripts/cartodb.uncompressed.js

Writing & running tests

Tests reside in the lib/assets/test directory. We use

• Jasmine 2.1 as test framework
• SinonJS 1.3.4 for test spies/stubs/mocks when Jasmine spies isn't good enough

When adding new files make sure they exist in an appropriate file located in lib/build/js_files (will depends if you're writing tests for current code or the newer browserify modules).

Until our guidelines are publically available follow the existing file/directory and style structure.

All tests can be run by:

grunt jasmine

# or if you want to run tests in browser it's preferrable to use:
grunt jasmine-server

If you only want to run a subset of tests the easiest and fastest way is to use focused tests, but you can also append ?spec=str-matching-a-describe to test URL, or use --filter flag if running tests in a terminal.

Grunt

We use Grunt to automate build tasks related to both CSS and JS.

We use v0.10.x of node (we recommend to use NVM).

Install dependencies using a normal npm install as such:

npm install
npm install -g grunt-cli

Run grunt availabletasks to see available tasks.

First time starting to work you need to run grunt, to build all static assets (will be written to public/assets/:version).

After that, for typical frontend work, it's recommended to run once:

grunt

This will generate all necessary frontend assets, and then:

grunt dev

That enables CSS and JS watchers for rebuilding bundles automatically upon changes.

Note! Make sure config/app_config.yml don't contain the app_assets configuration, i.e.:

# Make sure the following lines are removed, or commented like this:
#app_assets:

#  asset_host: '//cartodb-libs.global.ssl.fastly.net/cartodbui'

Don't forget to restart Rails after you have modified config/app_config.yml.

Submitting contributions

Before opening a pull request (or submitting a contribution) you will need to sign a Contributor License Agreement (CLA) before making a submission, learn more here.

After that, there are several rules you should follow when a new pull request is created:

• Title has to be descriptive. If you are fixing a bug don't use the ticket title or number.
• Explain what you have achieved in the description and choose a reviewer (it has to be a CartoDB team member) of your code. If you have doubts, just ask for one.
• If you change something related with the UI of the application:
  • Add an image or an animation (LiceCap is your friend) about the feature you have just implemented. Or show the change against what it is already done.
  • Change UI assets version, present in package.json file. Minor if it is a bugfixing or a small feature, major when it is a big change.
• Our linter machine, Hound, should not trigger any warnings about your changes.
• All tests should pass, both for JS and Ruby.