We'd love to accept your sample apps and patches! Before we can take them, we have to jump a couple of legal hurdles.
Please fill out either the individual or corporate Contributor License Agreement (CLA).
- If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an [individual CLA] (https://developers.google.com/open-source/cla/individual).
- If you work for a company that wants to allow you to contribute your work, then you'll need to sign a [corporate CLA] (https://developers.google.com/open-source/cla/corporate).
Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests.
- Submit an issue describing your proposed change to the repo in question.
- The repo owner will respond to your issue promptly.
- If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
- Fork the desired repo, develop and test your code changes.
- Ensure that your code adheres to the existing style in the sample to which you are contributing.
- Ensure that your code has an appropriate set of unit tests which all pass.
- Submit a pull request.
Samples in this repository follow the GitHub Ruby Styleguide except where noted otherwise.
Align variables to improve the readability of embedded code snippets.
# good
storage_client = Google::Cloud::Storage.new
bucket = storage.create_bucket "my-bucket"
uploaded_file = bucket.file "my-file.txt"
# bad
storage_client = Google::Cloud::Storage.new
bucket = storage.create_bucket "my-bucket"
uploaded_file = bucket.file "my-file.txt"This repository holds the samples used in the Ruby documentation on cloud.google.com.
There are two distinctly different types of samples:
Reference snippets are isolated snippets that demonstrate how to perform a specific task such as creating a Google Cloud Storage bucket.
Tutorial applications are sample applications that demonstrate how to use one or more Google APIs and products to create a fully-functioning application.
Specific blocks of code that are embedded in documentation
are defined using [START snippet_name] and [END snippet_name]
region tags.
Example:
def create_bucket project_id:, bucket_name:
# [START create_bucket]
# project_id = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"
require "google/cloud/storage"
storage = Google::Cloud::Storage.new project: project_id
bucket = storage.create_bucket bucket_name
puts "Created bucket #{bucket.name}"
# [END create_bucket]
endReference snippets are isolated snippets that demonstrate how to perform a specific task such as creating a Google Cloud Storage bucket.
Ideally, developers should be able to copy/paste the code in a reference snippet and run it after replacing placeholder values.
When a code snippet makes use of variables that are defined outside of the snippet, add commented-out variable declarations to the top of the snippet.
Example:
# project_id = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"
require "google/cloud/storage"
storage = Google::Cloud::Storage.new project: project_idReference snippets should include the require statement(s) necessary
to import relevant dependencies for the code sample.
If a snippet uses a Google Cloud client library, it should be required in the snippet. This documents how to require the client library.
Example:
# project_id = "Your Google Cloud project ID"
# bucket_name = "Your Google Cloud Storage bucket name"
require "google/cloud/storage"
storage = Google::Cloud::Storage.new project: project_idNote: common libraries such as "date" and "time" do not need to be required within the snippet. Explicitly require dependencies that add value and should be documentated.
When possible, reference code snippets should be executable.
Each reference code snippet should be executable via a corresponding command-line application.
For example, the "create_bucket" snippet in "buckets.rb" should be
executable by running bundle exec ruby buckets.rb create
To make snippets executable, add a postable to the end of the file that calls the snippet's method.
For example:
def create_bucket project_id:, bucket_name:
# ...
end
if __FILE__ == $PROGRAM_NAME
command = ARGV.shift
case command
when "create"
create_bucket project_id: ENV["GOOGLE_CLOUD_PROJECT"],
bucket_name: ARGV.first
else
puts <<-usage
Usage: bundle exec ruby buckets.rb [command] [arguments]
Commands:
create <bucket> Create a new bucket with the provided name
Environment variables:
GOOGLE_CLOUD_PROJECT must be set to your Google Cloud project ID
usage
end
endArgument parsing is intentionally simple.
Tutorial applications are sample applications that demonstrate how to use one or more Google APIs and products to create a fully-functioning application.
A tutorial sample may include command-line application(s) or web application(s).
For example, the web applications in the appengine
directory are used by short tutorials.
The purpose of tutorial applications is very different from reference snippets.
A tutorial application should be an idiomatic Ruby application. Code snippets from tutorial applications demonstrate just a part of the whole application and are not isolated.
- Tutorial snippet may not include
requirestatements - Tutorial snippet may not include client library instantiation
- Tutorial snippet may not include placeholder variables
Here is an small example of the snippets that might be extracted from a fully implemented tutorial application:
require "google/cloud/pubsub"
@pubsub = Google::Cloud::Pubsub.newdef send_notification message
topic = @pubsub.topic "notifications"
topic.publish message
enddef get_latest_notifications
subscription = @pubsub.subscription "mobile-notifications"
messages = subscription.pull
notifications = messages.map { |msg| Notifiction.new msg.data }
notifications
end