From b2ae5b4e69ff02e39798a3c9b0bac20943d468ec Mon Sep 17 00:00:00 2001 From: Ryan Seys Date: Wed, 3 Sep 2014 19:13:07 -0400 Subject: [PATCH 1/2] Update documentation - CONTRIBUTING and README Update contributing instructions to be more clear on running reg tests Split up contributing into more parts to clarify different tests Add details to demos in README Add License section to README Travis badge link to travis etc --- CONTRIBUTING.md | 46 ++++++++++++++++++++++++++++++++++++---------- README.md | 32 +++++++++++++++++++++----------- 2 files changed, 57 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f29bf55c31f..046e206b68c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,30 +7,56 @@ ## Testing -``` sh -# Run the tests. -$ npm test +### Unit tests -# Run the regression tests. -$ npm run regression-test +To run the unit tests, simply run: -# See the test coverage report. -$ npm run cover +``` sh +$ npm test ``` -To run the regression tests, first create and configure a project following the [instructions on how to run gcloud-node][elsewhere]. After that, set the following environment variables: +### Regression Tests + +To run the regression tests, first create and configure a project in the Google Developers Console following the [instructions on how to run gcloud-node][elsewhere]. After that, set the following environment variables: - **GCLOUD_TESTS_PROJECT_ID**: Developers Console project's ID (e.g. bamboo-shift-455) - **GCLOUD_TESTS_BUCKET_NAME**: The name of the bucket to use for the Cloud Storage API tests - **GCLOUD_TESTS_KEY**: The path to the JSON key file. -Lastly, create the indexes used in the datastore regression tests using the [gcloud command-line tool][gcloudcli] and the indexes found in `regression/data/index/yaml`: +Install the [gcloud command-line tool][gcloudcli] to your machine and use it to create the indexes used in the datastore regression tests with indexes found in `regression/data/index/yaml`: + +From the project's root directory: ``` sh -# From the project's root directory: +# Install the app component +$ gcloud components update app + +# Set the default project in your env +$ gcloud config set project $GCLOUD_TESTS_PROJECT_ID + +# Authenticate the gcloud tool with your account +$ gcloud auth login + +# Create the indexes $ gcloud preview datastore create-indexes regression/data/ ``` +You may now run the regression tests: + +``` sh +$ npm run regression-test +``` + +### Test Coverage + +Generate the coverage report: + +``` sh +$ npm run cover +``` + +The test coverage report will be available in `coverage/`. + ## Contributor License Agreements Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA): diff --git a/README.md b/README.md index e281470cc55..81b5318dca7 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > Node idiomatic client for Google Cloud services. [![NPM Version](https://img.shields.io/npm/v/gcloud.svg)](https://www.npmjs.org/package/gcloud) -![Travis Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-node.svg) +[![Travis Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-node.svg)](https://travis-ci.org/GoogleCloudPlatform/gcloud-node/) [![Coverage Status](https://img.shields.io/coveralls/GoogleCloudPlatform/gcloud-node.svg)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-node?branch=master) This client supports the following Google Cloud services: @@ -42,25 +42,27 @@ If you are not running this client on Google Compute Engine, you need a Google D See the [Google Cloud Datastore docs](https://developers.google.com/datastore/docs/activate) for more details on how to activate Cloud Datastore for your project. -See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-datastore.html) to learn how to interact with the Cloud Datastore using this Client Library. +See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/module-datastore.html) to learn how to interact with the Cloud Datastore using this Client Library. ```js var gcloud = require('gcloud'); var datastore = gcloud.datastore; var dataset; -// From Google Compute Engine +// From Google Compute Engine: dataset = new datastore.Dataset({ projectId: 'my-project', }); -// From elsewhere +// Or from elsewhere: dataset = new datastore.Dataset({ projectId: 'my-project', - keyFilename: '/path/to/keyfile.json' + keyFilename: '/path/to/keyfile.json' }); -dataset.get(dataset.key('Product', 'Computer'), function(err, entity) {}); +dataset.get(dataset.key('Product', 'Computer'), function(err, entity) { + console.log(err || entity); +}); ``` ## Google Cloud Storage @@ -69,27 +71,35 @@ dataset.get(dataset.key('Product', 'Computer'), function(err, entity) {}); You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on the [Google Cloud Storage docs](https://developers.google.com/storage/docs/cloud-console#_creatingbuckets) to learn how to create a bucket. -See [the API documentation](https://googlecloudplatform.github.io/gcloud-node/module-storage.html) to learn how to connect to the Cloud Storage using this Client Library. +See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/module-storage.html) to learn how to connect to the Cloud Storage using this Client Library. ```js var gcloud = require('gcloud'); var storage = gcloud.storage; var bucket; -// From Google Compute Engine +// From Google Compute Engine: bucket = new storage.Bucket({ bucketName: YOUR_BUCKET_NAME }); -// From elsewhere +// Or from elsewhere: bucket = new storage.Bucket({ bucketName: YOUR_BUCKET_NAME, keyFilename: '/path/to/the/key.json' }); -bucket.write('filename', 'Hello World', function(err) {}); +bucket.write('demo.txt', 'Hello World', function(err) { + console.log(err || 'Created demo.txt'); +}); ``` ## Contributing -See [CONTRIBUTING](CONTRIBUTING.md). +Contributions to this library are always welcome and highly encouraged. + +See [CONTRIBUTING](CONTRIBUTING.md) for more information on how to get started. + +## License + +Apache 2.0 - See [COPYING](COPYING) for more information. From 2ec31fc1bc4454cbf201134299d6eaf35b2edf84 Mon Sep 17 00:00:00 2001 From: Ryan Seys Date: Wed, 3 Sep 2014 21:35:13 -0400 Subject: [PATCH 2/2] Update README API doc links --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 81b5318dca7..a4c652bf21e 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ If you are not running this client on Google Compute Engine, you need a Google D See the [Google Cloud Datastore docs](https://developers.google.com/datastore/docs/activate) for more details on how to activate Cloud Datastore for your project. -See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/module-datastore.html) to learn how to interact with the Cloud Datastore using this Client Library. +See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/#/docs/datastore) to learn how to interact with the Cloud Datastore using this Client Library. ```js var gcloud = require('gcloud'); @@ -71,7 +71,7 @@ dataset.get(dataset.key('Product', 'Computer'), function(err, entity) { You need to create a Google Cloud Storage bucket to use this client library. Follow the steps on the [Google Cloud Storage docs](https://developers.google.com/storage/docs/cloud-console#_creatingbuckets) to learn how to create a bucket. -See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/module-storage.html) to learn how to connect to the Cloud Storage using this Client Library. +See [the gcloud-node API documentation](https://googlecloudplatform.github.io/gcloud-node/#/docs/storage) to learn how to connect to the Cloud Storage using this Client Library. ```js var gcloud = require('gcloud');