cartodb/lib/assets/javascripts/cdb/CONTRIBUTING.md

How to contribute to CartoDB.js

1. CartoDB.js quick start
2. Being part of CartoDB.js
3. Filling a ticket
4. Contributing code
5. Completing documentation
6. Submitting contributions

CartoDB.js quick start

This is a little doc with the basis of CartoDB.js framework (TM), in other words, all you need to know to start workig with it wihout doing it wrong.

general info

• The framework(TM) is built on top of Backbone.js (so you can use jQuery and underscore everywhere).
• we use jasmine for testing (grunt test)
• cdb is the namespace, so all the components should be inside it, i.e cbd.geo.Map. (look into cartodb.js)
• code style guide: https://github.com/cartodb/cartodb/wiki/Javascript-style-guide

folders

• cartodb.js: this file contains the scopes for all the app, should be included first
• core
• geo
• lib
• test
• examples

core

This contains all the base classes, used in all the project:

• config: all the app config goes here. Accesible by cdb.config
• logging: never ever use console.log, use cbd.log.info, cdb.log.error and cdb.debug. error call will generate an error You can check errors with cbd.errors singleton (it is a backbone.Collection)
• view: DO NOT USE Backbone.View, use cbd.core.View instead. It tracks zombie views and make removing views safe.
• templates

general guidelines for views

• never ever change a view directly. For example a button that changes the state should change the model and the view should change when the models triggers the change event.

• call clean when your view will not be used anymore

• link model events in this way, even if you have binded the method. Notice the 3rd parameter (this)

  ·this.model.bind('change', this.callback, this);

• when you have to unlink the view from the model you can do:

  · this.model.unbind(null, null, this);

• if your view has model and listen events from it, add to realted models (will be free when you call clean):

  // inside the view this.add_related_model(this.whatevermodel);

## Being part of CartoDB.js If you are reading this file you are already part of CartoDB :). But you can always help the community contributing in the code or answering questions in any of the channels you can find us, our google group and stack exchange.

Filling a ticket

If you want to open a new issue in our repository, please follow these instructions:

1. Descriptive title.
2. Write a good description, it always helps.
3. Include your browser, OS and CartoDB.js version (it shows up in the browser console).
4. Specify the steps to reproduce the problem.
5. Try to add an example showing the problem (using JSFiddle, JSBin,...).

Contributing code

Best part of open source, collaborate in CartoDB.js code!. We like hearing from you, so if you have any bug fixed, or a new feature ready to be merged, those are the steps you should follow:

1. Fork the CartoDB.js repository.
2. Create a new branch in your forked repository.
3. Commit your changes. Add new tests if it is necessary (grunt test), remember to follow "How to build" steps.
4. Open a pull request.
5. Any of the CartoDB.js mantainers will take a look.
6. If everything works, it will merged and released \o/.

If you want more detailed information, this GitHub guide is a must.

Completing documentation

CartoDB.js documentation is located in doc/API.md. That file is the content that appears in CartoDB platform documentation. Just follow the instructions described in contributing code and after accepting your pull request, we will make it appear online :).

Submitting contributions

You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.