Skip to content

Latest commit

 

History

History
168 lines (110 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

168 lines (110 loc) · 6.21 KB
Raw

Contributing to google-cloud-ruby

  1. Sign one of the contributor license agreements below.
  2. Fork the repo, develop and test your code changes.
  3. Send a pull request.

Contributor License Agreements

Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):

  • If you are an individual writing original source code and you own the intellectual property, then you'll need to sign an individual CLA.
  • If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.

You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.

Setup

In order to use the google-cloud-ruby console and run the project's tests, there is a small amount of setup:

  1. Install Ruby. google-cloud-ruby requires Ruby 2.0+. You may choose to manage your Ruby and gem installations with RVM, rbenv, or chruby.

  2. Install Bundler.

    $ gem install bundler

  3. Install the project dependencies.

    $ bundle install

Console

In order to run code interactively, you can automatically load google-cloud-ruby and its dependencies in IRB with:

$ bundle exec rake console

Tests

Tests are very important part of google-cloud-ruby. All contributions should include tests that ensure the contributed code behaves as expected.

Unit Tests

To run the unit tests, simply run:

$ rake test

Acceptance Tests

The google-cloud-ruby acceptance tests interact with the following live service APIs:

  • BigQuery
  • Cloud Datastore
  • Cloud DNS
  • Cloud Pub/Sub
  • Cloud Storage

Follow the instructions in the Authentication guide for enabling APIs. Some of the APIs may not yet be generally available, making it difficult for some contributors to successfully run the entire acceptance test suite. However, please ensure that you do successfully run acceptance tests for any code areas covered by your pull request.

To run the acceptance tests, first create and configure a project in the Google Developers Console, as described in the Authentication guide. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and the KEYFILE location on your system.

Datastore acceptance tests

To run the Datastore acceptance tests, you must first create indexes used in the tests.

Datastore indexes

Install the gcloud command-line tool and use it to create the indexes used in the datastore acceptance tests. 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 PROJECT_ID

# Authenticate the gcloud tool with your account
$ gcloud auth login

# Create the indexes
$ gcloud preview datastore create-indexes acceptance/data/

DNS Acceptance Tests

To run the DNS acceptance tests you must give your service account permissions to a domain name in Webmaster Central and set the GCLOUD_TEST_DNS_DOMAIN environment variable to the fully qualified domain name. (e.g. "example.com.")

Running the acceptance tests

To run the acceptance tests:

$ rake test:acceptance[PROJECT_ID,KEYFILE_PATH]

Or, if you prefer you can store the values in the GCLOUD_TEST_PROJECT and GCLOUD_TEST_KEYFILE environment variables:

$ export GCLOUD_TEST_PROJECT=my-project-id
$ export GCLOUD_TEST_KEYFILE=/path/to/keyfile.json
$ rake test:acceptance

If you want to use different values for Datastore vs. Storage acceptance tests, for example, you can use the DATASTORE_TEST_ and STORAGE_TEST_ environment variables:

$ export DATASTORE_TEST_PROJECT=my-project-id
$ export DATASTORE_TEST_KEYFILE=/path/to/keyfile.json
$ export STORAGE_TEST_PROJECT=my-other-project-id
$ export STORAGE_TEST_KEYFILE=/path/to/other/keyfile.json
$ rake test:acceptance

Integration Tests

The google-cloud-ruby integration tests are end-to-end tests that validate library functionality on real Google Cloud Platform hosting environments. The integration process deploys a test Rack-based application to Google Cloud Platform, then validates google-cloud-ruby code by making requests to this test application.

All integration tests require Cloud SDK for deployment. Following the instructions in Authentication guide for installation and authentication. Make sure a project ID is set:

$ gcloud config set project PROJECT_ID

Running integration tests on Google App Engine

To run the integration tests on Google App Engine:

$ rake integration:gae

Running integration tests on Google Container Engine

Google Container Engine requires docker for building docker images, and the Kubernetes commandline tool for image deployment. Follow the docker website for installation instructions.

The Kubernetes commandline tool can be installed through Cloud SDK:

$ gcloud components update kubectl

To run the integration tests on Google Container Engine:

$ rake integration:gke

Coding Style

Please follow the established coding style in the library. The style is is largely based on The Ruby Style Guide with a few exceptions based on seattle-style:

  • Avoid parenthesis when possible, including in method definitions.
  • Always use double quotes strings. (Option B)

You can check your code against these rules by running Rubocop like so:

$ rake rubocop

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Code of Conduct for more information.