From e45608ecdec0a91649fab7ef77aaefa088bba7cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Garc=C3=ADa=20Aubert?= Date: Fri, 27 Dec 2019 16:30:01 +0100 Subject: [PATCH] Update NEWS with latest changes --- CONTRIBUTING.md | 11 ----- HOWTO_RELEASE | 17 ------- HOWTO_RELEASE.md | 15 ++++++ README.md | 123 +++++++++++++++++++++++++++++++---------------- 4 files changed, 96 insertions(+), 70 deletions(-) delete mode 100644 CONTRIBUTING.md delete mode 100644 HOWTO_RELEASE create mode 100644 HOWTO_RELEASE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index b327c106..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,11 +0,0 @@ -Contributing ---- - -The issue tracker is at [github.com/CartoDB/CartoDB-SQL-API](https://github.com/CartoDB/CartoDB-SQL-API). - -We love pull requests from everyone, see [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/#contributing). - - -## Submitting Contributions - -* You will need to sign a Contributor License Agreement (CLA) before making a submission. [Learn more here](https://carto.com/contributions). diff --git a/HOWTO_RELEASE b/HOWTO_RELEASE deleted file mode 100644 index bf956ca4..00000000 --- a/HOWTO_RELEASE +++ /dev/null @@ -1,17 +0,0 @@ -1. Test (make clean all check), fix if broken before proceeding -2. Ensure proper version in package.json and package-lock.json -3. Ensure NEWS section exists for the new version, review it, add release date -4. Commit package.json, package.json and, NEWS -5. git tag -a Major.Minor.Patch # use NEWS section as content -6. Stub NEWS/package for next version - -Versions: - -Bugfix releases increment Patch component of version. -Feature releases increment Minor and set Patch to zero. -If backward compatibility is broken, increment Major and -set to zero Minor and Patch. - -Branches named 'b.' are kept for any critical -fix that might need to be shipped before next feature release -is ready. diff --git a/HOWTO_RELEASE.md b/HOWTO_RELEASE.md new file mode 100644 index 00000000..6bbda918 --- /dev/null +++ b/HOWTO_RELEASE.md @@ -0,0 +1,15 @@ +# How to release + +1. Test (npm test), fix if broken before proceeding. +2. Ensure proper version in `package.json` and `package-lock.json`. +3. Ensure NEWS section exists for the new version, review it, add release date. +4. Commit `package.json`, `package-lock.json`, NEWS. +5. Run `git tag -a Major.Minor.Patch`. Use NEWS section as content. +6. Stub NEWS/package for next version. + +## Versions + +* Bugfix releases increment Patch component of version. +* Feature releases increment Minor and set Patch to zero. +* If backward compatibility is broken, increment Major and set to zero Minor and Patch. +* Branches named 'b.' are kept for any critical fix that might need to be shipped before next feature release is ready. diff --git a/README.md b/README.md index 0cbca8fe..3b46664b 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,111 @@ -SQL API for carto.com -======================== +# CartoDB-SQL-API [![Build Status](https://travis-ci.org/CartoDB/CartoDB-SQL-API.svg?branch=master)](https://travis-ci.org/CartoDB/CartoDB-SQL-API) -[![Build Status](https://travis-ci.org/CartoDB/CartoDB-SQL-API.png?branch=master)](https://travis-ci.org/CartoDB/CartoDB-SQL-API) +The [`CARTO SQL API`](https://carto.com/developers/sql-api/). Provides a web service for running SQL queries and jobs against your account in CARTO: -Provides a node.js based API for running SQL queries against CartoDB. +* Run queries with fine-grained permissions through [`Auth API`](https://carto.com/developers/auth-api/). +* Schedule jobs using [`Batch Queries`](https://carto.com/developers/sql-api/guides/batch-queries/). -* Users are authenticated over OAuth or via an API KEY. -* Authenticated requests to this API should always be made over SSL. +## Build +Requirements: -## Requirements - -* Node 10.x -* npm 6.x -* PostgreSQL >= 10.0 -* PostGIS >= 2.4 -* CARTO Postgres Extension >= 0.24.1 -* Redis >= 4 +* [`Node 10.x (npm 6.x)`](https://nodejs.org/dist/latest-v10.x/) +* [`PostgreSQL >= 10.0`](https://www.postgresql.org/download/) +* [`PostGIS >= 2.4`](https://postgis.net/install/) +* [`CARTO Postgres Extension >= 0.24.1`](https://github.com/CartoDB/cartodb-postgresql) +* [`Redis >= 4`](https://redis.io/download) * GDAL `1.11.0` (bin utils). See [installing GDAL](http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries) * zip commandline tool. -* C++11 (to build internal dependencies if needed) +* `C++11` to build internal dependencies. When there's no pre-built binaries for your OS/architecture distribution. + +Optional: + +* [`Varnish`](http://www.varnish-cache.org) +* [`Statsd`](https://github.com/statsd/statsd) + +### PostGIS setup + +A `template_postgis` database is expected. One can be set up with + +```shell +$ createdb --owner postgres --template template0 template_postgis +$ psql -d template_postgis -c 'CREATE EXTENSION postgis;' +``` +### Install -## Install dependencies +To fetch and build all node-based dependencies, run: -```sh +```shell $ npm install ``` -## Usage +### Run +Create the `./config/environments/.js` file (there are `.example` files to start from). -Create and edit config/environments/.js from .js.example files. -You may find the ./configure script useful to make an edited copy for you, -see ```./configure --help``` for a list of supported switches. +```shell +$ node app.js +``` -Make sure redis is running and knows about active cartodb user. +Where `` is the name of a configuration file under `./config/environments/`. -Make sure your PostgreSQL server is running, is accessible on -the host and port specified in the file, has -a 'publicuser' role (or whatever you set ``db_pubuser`` configuration -directive to) and trusts user authentication from localhost -connections. +### Test -```sh -node app.js +```shell +$ npm test ``` -Supported values are development, test, production +### Coverage -See doc/API.md for API documentation. -For examples of use, see under test/. +```shell +$ npm run cover +``` +Open `./coverage/lcov-report/index.html`. -## Tests +### Docker support -Run with: +We provide docker images just for testing and continuous integration purposes: -```sh -$ npm test +* [`nodejs-xenial-pg1121`](https://hub.docker.com/r/carto/nodejs-xenial-pg1121/tags) +* [`nodejs-xenial-pg101`](https://hub.docker.com/r/carto/nodejs-xenial-pg101/tags) + +You can find instructions to install Docker, download, and update images [here](https://github.com/CartoDB/Windshaft-cartodb/blob/master/docker/reference.md). + +### Useful `npm` scripts + +Run test in a docker image with a specific Node.js version: + +```shell +$ DOCKER_IMAGE= NODE_VERSION= npm run test:docker +``` + +Where: + +* ``: the tag of required docker image, e.g. `carto/nodejs-xenial-pg1121:latest` +* ``: the Node.js version, e.g. `10.15.1` + +In case you need to debug: + +```shell +$ DOCKER_IMAGE= npm run docker:bash ``` -If any issue arise see test/README.md +## Documentation + +You can find an overview, guides, full reference, and support in [`CARTO's developer center`](https://carto.com/developers/sql-api/). The [docs directory](https://github.com/CartoDB/CartoDB-SQL-API/tree/master/docs) contains different documentation resources, from a higher level to more detailed ones. + +## Contributing + +* The issue tracker: [`Github`](https://github.com/CartoDB/CartoDB-SQL-API/issues). +* We love Pull Requests from everyone, see [contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/#contributing). +* You'll need to sign a Contributor License Agreement (CLA) before submitting a Pull Request. [Learn more here](https://carto.com/contributions). + +## Versioning -Note that the environment should be set to ensure the default -PostgreSQL user is superuser (PGUSER=postgres make check). +We follow [`SemVer`](http://semver.org/) for versioning. For available versions, see the [tags on this repository](https://github.com/CartoDB/CartoDB-SQL-API/tags). -Contributing ---- +## License -See [CONTRIBUTING.md](CONTRIBUTING.md). +This project is licensed under the BSD 3-clause "New" or "Revised" License. See the [LICENSE](LICENSE) file for details.