From 11484fb10c35f0867e9281398236cdbf21b98f64 Mon Sep 17 00:00:00 2001 From: Nicklas Gummesson Date: Fri, 12 Dec 2014 19:11:50 +0100 Subject: [PATCH] Update documentation --- CONTRIBUTING.md | 90 +++++++++++++++++++++++ README.md | 104 +++++++++++++++++---------- doc/{frontend/org.md => frontend.md} | 13 ++-- lib/build/README.md | 14 ---- lib/build/UPGRADING.md | 50 ------------- 5 files changed, 162 insertions(+), 109 deletions(-) create mode 100644 CONTRIBUTING.md rename doc/{frontend/org.md => frontend.md} (91%) delete mode 100644 lib/build/README.md delete mode 100644 lib/build/UPGRADING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..b285ee0a6c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,90 @@ +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 + +# General + +Every new feature (as well as bugfixes) should come with a test case. Depending on context different guidelines might +apply, see following sections. + +If you +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`: + +```ruby +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`._ + +# Frontend + +The frontend is really standalone code, but is integrated with/served by the Rails application. + +## JS + +We use plain old JS and an older version of +[BackboneJS](http://htmlpreview.github.io/?https://raw.github.com/jashkenas/backbone/0.9.2/index.html), +since the UI is built on top of [CartoDB.js](https://github.com/CartoDB/cartodb.js). + +Source code is located at `lib/assets/javascripts`. + +See [doc/frontend.md] for further details. + +Until our guidelines are publically available follow the existing file/directory and style structure. + +### Writing testcases + +Tests reside in the `lib/assets/test` directory. We use + - [Jasmine 2.1](jasmine.github.io/2.1/introduction.html) as test framework + - [SinonJS](sinonjs.org) for test spies/stubs/mocks when Jasmine spies isn't good enough + - [Rewirefy](https://github.com/i-like-robots/rewireify) to mock CommonJS `require` calls + +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. + +## CSS + +We use [SASS](http://sass-lang.com/), + with [`.scss`](http://www.thesassway.com/editorial/sass-vs-scss-which-syntax-is-better) format. + +Source files are located at `app/assets/stylesheets`. We used to use Rails sprockets pipeline, + but nowadays migrated to [Grunt](#grunt) (see that section for details). + +See [doc/frontend.md] for further details. + +Until our guidelines are publically available follow the existing file/directory and style structure. + +## Grunt + +We use [Grunt](http://gruntjs.com/) to automate build tasks related to both CSS and JS. + +We use v0.10.x of [node](http://nodejs.org/) (we recommend to use [NVM](https://github.com/creationix/nvm)). + +Install dependencies using a normal npm install as such: +```bash +npm install +npm install -g grunt-cli +``` + +Run `npm grunt availabletasks` to see available tasks. + +For a standard developer we recommend `npm grunt dev`, which watches CSS/JS files and rebuild bundles automatically on +file changes. The compiled code can be seen under `public/assets/:version` + +**Note!** Make sure `config/app_config.yml` don't contain the `app_assets` configuration, i.e.: + +```ruby +# 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`._ + diff --git a/README.md b/README.md index b9d1d301fa..8b3bbd0d74 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,27 @@ We hope you like it! ![Map View](http://cartodb.s3.amazonaws.com/github/map_view.png) +--- +## Table of Contents + +- [What can I do with CartoDB?](#what-can-i-do-with-cartodb) +- [What are the components of CartoDB](#what-are-the-components-of-cartodb) +- [How do I install CartoDB?](#how-do-i-install-cartodb) + - [Dependencies](#what-does-cartodb-depend-on) + - ... + - [Install problems and common solutions](#install-problems-and-common-solutions) +- [Running CartoDB](#running-cartodb) + - [Note on tiling SQL API and Redis](#note-on-tiling-sql-api-and-redis) + - [Handy tasks](#handy-tasks) + - [Using foreman](#using-foreman) +- [Developing CartoDB](#developing-cartodb) + - [Frontend (JS/CSS)](#frontend-js-css) + - [Contributing] +- [How do I Upgrade CartodB?](#how-do-i-upgrade-cartodb) +- [Testing](#testing) +- [Contributors](#contributors) + +--- # What can I do with CartoDB? # @@ -48,22 +69,6 @@ and code. - A Map tiler that supports SQL and tile styling using CartoCSS - Authentication using OAuth if required -# What does CartoDB depend on? # - - - Ubuntu 12.04 - - Postgres 9.3.x (with plpythonu extension) - - [cartodb-postgresql](https://github.com/CartoDB/cartodb-postgresql) extension - - Redis 2.2+ - - Ruby 1.9.3 - - Node.js 0.10.x - - CartoDB-SQL-API - - GEOS 3.3.4 - - GDAL 1.10.x (Starting with CartoDB 2.2.0) - - PostGIS 2.1.x - - Mapnik 2.1.1 - - Windshaft-cartodb - - Varnish 2.1+ (WARNING: must be < 3.0!) - - ImageMagick 6.6.9+ (for the testsuite) # How do I install CartoDB? # @@ -92,6 +97,25 @@ $ git clone --recursive https://github.com/CartoDB/cartodb.git Or you can just [download the CartoDB zip file](https://github.com/CartoDB/cartodb/archive/master.zip). + +## What does CartoDB depend on? # + + - Ubuntu 12.04 + - Postgres 9.3.x (with plpythonu extension) + - [cartodb-postgresql](https://github.com/CartoDB/cartodb-postgresql) extension + - Redis 2.2+ + - Ruby 1.9.3 + - Node.js 0.10.x + - CartoDB-SQL-API + - GEOS 3.3.4 + - GDAL 1.10.x (Starting with CartoDB 2.2.0) + - PostGIS 2.1.x + - Mapnik 2.1.1 + - Windshaft-cartodb + - Varnish 2.1+ (WARNING: must be < 3.0!) + - ImageMagick 6.6.9+ (for the testsuite) + + ## Add CartoDB [PPA](https://help.ubuntu.com/community/PPA)s ## First install python software properties to be able to run `add-apt-repository` @@ -431,17 +455,18 @@ node app.js development sudo apt-get install imagemagick ``` -## Optional +## Optional installation These are not strictly required to run CartoDB, but if you are installing CartoDB to do change something you might need them: -### Frontend assets -Have their own README and tools since they don't run on the Rails, see [lib/build/README.md](lib/build/README.md). - ### Raster import support Raster importer needs `raster2pgsql` to be in your path. You can check whether it's available by running `which raster2pgsql`. If it's not, you should link it: `$ sudo ln -s /usr/local/src/postgis-2.1.2/raster/loader/raster2pgsql /usr/bin/`. Access to temporary dir is also needed. Depending on your installation you might also need to run `sudo chown 501:staff /usr/local/src/postgis-2.1.2/raster/loader/.libs` (maybe replacing `501:staff` with your installation /usr/local/src/postgis-2.1.2/raster/loader/ group and owner). +## Install problems and common solutions # + +Installing the full stack might not always be smooth due to other component updates, so if you run into problems installing CartoDB, please check [this list of problems and solutions](https://github.com/CartoDB/cartodb/wiki/Problems-faced-during-CartoDB-install-&-solutions-if-known) first to see if your problem already happened in the past and somebody else found a workaround, solution or fix to it. + ## Install local instance of cold beer ## Congratulations! @@ -517,14 +542,16 @@ You should now be able to access **`http://.localhost.lan:3000`** in your browser and login with the password specified above. -# How do I upgrade CartoDB? # +## Note on tiling, SQL API and Redis -See UPGRADE file for instructions about upgrading CartoDB. +Please ensure CartoDB-SQL-API, Windshaft-cartodb, and Redis are all +running for full experience. -For upgrade of Windshaft-CartoDB and CartoDB-SQL-API see the relative -documentation. +Manual configuration is needed for the +`public/javascripts/environments/development.js` file which configures +Windshaft-cartodb tile server URLs. -# Handy tasks # +## Handy tasks For a full list of CartoDB utility tasks: @@ -532,8 +559,7 @@ For a full list of CartoDB utility tasks: bundle exec rake -T ``` - -# Using foreman # +## Using foreman You can also use foreman to run the full stack (cartodb server, sql api, tiler, redis and resque), using a single command: IMPORTANT: You need to install foreman by yourself. It's not included in the Gemfile. Run this: @@ -549,26 +575,28 @@ bundle exec foreman start -p $PORT where $PORT is the port you want to attach the rails server to. -# Note on tiling, SQL API and Redis # +# How do I upgrade CartoDB? # -Please ensure CartoDB-SQL-API, Windshaft-cartodb, and Redis are all -running for full experience. +See [UPGRADE](UPGRADE) for instructions about upgrading CartoDB. -Manual configuration is needed for the -`public/javascripts/environments/development.js` file which configures -Windshaft-cartodb tile server URLs. +For upgrade of Windshaft-CartoDB and CartoDB-SQL-API see the relative +documentation. +# Developing CartoDB -# Install problems and common solutions # +## Frontend (JS/CSS) -Installing the full stack might not always be smooth due to other component updates, so if you run into problems installing CartoDB, please check [this list of problems and solutions](https://github.com/CartoDB/cartodb/wiki/Problems-faced-during-CartoDB-install-&-solutions-if-known) first to see if your problem already happened in the past and somebody else found a workaround, solution or fix to it. +See [doc/frontend.md](doc/frontend.md) + +## Contributing +See [CONTRIBUTING.md](CONTRIBUTING.md) for how you can improve CartoDB. :) -### Testing ### +# Testing -See TESTING.md +See [TESTING.md](TESTING.md) -### Contributors ### +# Contributors - Fernando Blat ([ferblape](https://twitter.com/ferblape)) - Javier Álvarez Medina ([xavijam](https://twitter.com/xavijam)) diff --git a/doc/frontend/org.md b/doc/frontend.md similarity index 91% rename from doc/frontend/org.md rename to doc/frontend.md index 9434d2922d..c71275ff76 100644 --- a/doc/frontend/org.md +++ b/doc/frontend.md @@ -1,18 +1,17 @@ +# Frontend documentation -# organizations +## Organizations -this document contains some notes on how to work with backbone models related to organization +This document contains some notes on how to work with backbone models related to organization -## models related to organization +## Models related to organization - [cdb.admin.User](https://github.com/CartoDB/cartodb/blob/CDB-2891/lib/assets/javascripts/cartodb/models/user.js): it already existed, but it takes more importance - [cdb.admin.Organization](https://github.com/CartoDB/cartodb/blob/CDB-2891/lib/assets/javascripts/cartodb/models/organization.js): this represents an organization - [cdb.admin.Permission](https://github.com/CartoDB/cartodb/blob/CDB-2891/lib/assets/javascripts/cartodb/models/permissions.js): permission object, contains the information to know about the ownership and permission list (called ``acl``) of an object. See https://github.com/Vizzuality/cartodb-management/wiki/multiuser-REST-API#permissions-object - - -## changes +### Changes - ``User`` model has an organization attribute. Each user is **always** inside an organization, so this will be always filled. When the organization contains only a user, the application behavior is the @@ -21,7 +20,7 @@ this document contains some notes on how to work with backbone models related to - ``Visualization`` object contains a ``permission`` attribute (instance of ``cdb.admin.Permission``) -## how to use them +### How to use them - add read permissions to a table diff --git a/lib/build/README.md b/lib/build/README.md deleted file mode 100644 index 278a79252d..0000000000 --- a/lib/build/README.md +++ /dev/null @@ -1,14 +0,0 @@ - -# how to build frontend assets - -- install node (0.10.x) recommended -- install dependencies: -``` -npm install -``` -- execute grunt -``` -grunt -``` - -the assets are created in `public/assets/:version/` and after this you can run rails app as always diff --git a/lib/build/UPGRADING.md b/lib/build/UPGRADING.md deleted file mode 100644 index e7dc648ba7..0000000000 --- a/lib/build/UPGRADING.md +++ /dev/null @@ -1,50 +0,0 @@ - -# upgrading to new assets pipeline - -We have changed the rails assets pipeline to a custom one in order to take control and save -development and deployement time. - -There are a few things that change related to deployment and development, below you can find the -different use cases. - -## development - -If you are developing cartodb frontend you need to follow the steps in README file, every time you -change javascript or css you need to compile it. You can use watch task: - -``` -grunt watch:js -``` - -so every time javascript is changed the files are compiled - -**If you are developing something not related to frontend** you don't need to compile anything, change your ``confg/app_config.yml`` - -``` - app_assets: - asset_host: '//cartodb-libs.global.ssl.fastly.net/cartodbui' -``` - -and reload rails server - -## deployment - -### in the cloud -assets dont' need to be precompiled by rails, it's done by release task: - -``` -grunt --environment production release -``` - - -### custom installs - -just follow steps in README.md and then: - -``` -grunt release -``` - -config/enviorment/staging.rb need to remove ``app_assets`` from ``config/app_config.yml`` so assets -are loaded from local -