94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
## How to contribute to CartoDB.js
|
||
|
||
1. [CartoDB.js quick start](#cartodbjs-framework-quick-start)
|
||
2. [Being part of CartoDB.js](#being-part-of-cartodbjs)
|
||
3. [Filling a ticket](#filling-a-ticket)
|
||
4. [Contributing code](#contributing-code)
|
||
5. [Completing documentation](#completing-documentation)
|
||
6. [Submitting contributions](#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](#Contributing-code) or answering questions in any of the channels you can find us, [our google group](https://groups.google.com/forum/#!forum/cartodb) and [stack exchange](http://gis.stackexchange.com/questions/tagged/cartodb).
|
||
|
||
|
||
## 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](http://jsfiddle.net), [JSBin](http://jsbin.com),...).
|
||
|
||
|
||
## 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"](https://github.com/CartoDB/cartodb.js/blob/master/README.md#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](https://guides.github.com/activities/contributing-to-open-source/) 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](http://docs.cartodb.com/cartodb-platform/cartodb-js.html).
|
||
Just follow the instructions described in [contributing code](#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](https://carto.com/contributions).
|