google-cloud-storage 1.14.0 → 1.14.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/AUTHENTICATION.md +178 -0
- data/CHANGELOG.md +167 -0
- data/CODE_OF_CONDUCT.md +40 -0
- data/CONTRIBUTING.md +188 -0
- data/LOGGING.md +27 -0
- data/OVERVIEW.md +573 -0
- data/TROUBLESHOOTING.md +37 -0
- data/lib/google/cloud/storage/version.rb +1 -1
- metadata +9 -3
- data/README.md +0 -100
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 349f612cd2d7620e74e3488ba4da57918288ca32328ed0e7be988c3848ec39ff
|
|
4
|
+
data.tar.gz: 14a9285c48557ca8f71909c63e049c9427581f1340cad9fc685b2ef473d84d13
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 0a3de34c94ffdd04627638f46fb1f5076e128967982114fdd33b5232aa2375f53c4916b95df972a803af5c2d2ecdf235a4306a5c94398911e19fac6d56018936
|
|
7
|
+
data.tar.gz: 64c0cf9b35db7084e931fc4779bf7eec1fc159b77a7eee27b2f9d92e30c61c683def31766e419544de1c04512771b5a74da0f624951a0e96c17d726961285e82
|
data/AUTHENTICATION.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Authentication
|
|
2
|
+
|
|
3
|
+
In general, the google-cloud-storage library uses [Service
|
|
4
|
+
Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
|
|
5
|
+
credentials to connect to Google Cloud services. When running on Compute Engine
|
|
6
|
+
the credentials will be discovered automatically. When running on other
|
|
7
|
+
environments, the Service Account credentials can be specified by providing the
|
|
8
|
+
path to the [JSON
|
|
9
|
+
keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
|
|
10
|
+
the account (or the JSON itself) in environment variables. Additionally, Cloud
|
|
11
|
+
SDK credentials can also be discovered automatically, but this is only
|
|
12
|
+
recommended during development.
|
|
13
|
+
|
|
14
|
+
## Project and Credential Lookup
|
|
15
|
+
|
|
16
|
+
The google-cloud-storage library aims to make authentication as simple as
|
|
17
|
+
possible, and provides several mechanisms to configure your system without
|
|
18
|
+
providing **Project ID** and **Service Account Credentials** directly in code.
|
|
19
|
+
|
|
20
|
+
**Project ID** is discovered in the following order:
|
|
21
|
+
|
|
22
|
+
1. Specify project ID in method arguments
|
|
23
|
+
2. Specify project ID in configuration
|
|
24
|
+
3. Discover project ID in environment variables
|
|
25
|
+
4. Discover GCE project ID
|
|
26
|
+
|
|
27
|
+
**Credentials** are discovered in the following order:
|
|
28
|
+
|
|
29
|
+
1. Specify credentials in method arguments
|
|
30
|
+
2. Specify credentials in configuration
|
|
31
|
+
3. Discover credentials path in environment variables
|
|
32
|
+
4. Discover credentials JSON in environment variables
|
|
33
|
+
5. Discover credentials file in the Cloud SDK's path
|
|
34
|
+
6. Discover GCE credentials
|
|
35
|
+
|
|
36
|
+
### Google Cloud Platform environments
|
|
37
|
+
|
|
38
|
+
While running on Google Cloud Platform environments such as Google Compute
|
|
39
|
+
Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
|
|
40
|
+
The **Project ID** and **Credentials** and are discovered automatically. Code
|
|
41
|
+
should be written as if already authenticated. Just be sure when you [set up the
|
|
42
|
+
GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
|
|
43
|
+
access. For example:
|
|
44
|
+
|
|
45
|
+
* **All APIs**
|
|
46
|
+
* `https://www.googleapis.com/auth/cloud-platform`
|
|
47
|
+
* `https://www.googleapis.com/auth/cloud-platform.read-only`
|
|
48
|
+
* **BigQuery**
|
|
49
|
+
* `https://www.googleapis.com/auth/bigquery`
|
|
50
|
+
* `https://www.googleapis.com/auth/bigquery.insertdata`
|
|
51
|
+
* **Compute Engine**
|
|
52
|
+
* `https://www.googleapis.com/auth/compute`
|
|
53
|
+
* **Datastore**
|
|
54
|
+
* `https://www.googleapis.com/auth/datastore`
|
|
55
|
+
* `https://www.googleapis.com/auth/userinfo.email`
|
|
56
|
+
* **DNS**
|
|
57
|
+
* `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
|
|
58
|
+
* **Pub/Sub**
|
|
59
|
+
* `https://www.googleapis.com/auth/pubsub`
|
|
60
|
+
* **Storage**
|
|
61
|
+
* `https://www.googleapis.com/auth/devstorage.full_control`
|
|
62
|
+
* `https://www.googleapis.com/auth/devstorage.read_only`
|
|
63
|
+
* `https://www.googleapis.com/auth/devstorage.read_write`
|
|
64
|
+
|
|
65
|
+
### Environment Variables
|
|
66
|
+
|
|
67
|
+
The **Project ID** and **Credentials JSON** can be placed in environment
|
|
68
|
+
variables instead of declaring them directly in code. Each service has its own
|
|
69
|
+
environment variable, allowing for different service accounts to be used for
|
|
70
|
+
different services. (See the READMEs for the individual service gems for
|
|
71
|
+
details.) The path to the **Credentials JSON** file can be stored in the
|
|
72
|
+
environment variable, or the **Credentials JSON** itself can be stored for
|
|
73
|
+
environments such as Docker containers where writing files is difficult or not
|
|
74
|
+
encouraged.
|
|
75
|
+
|
|
76
|
+
The environment variables that Storage checks for project ID are:
|
|
77
|
+
|
|
78
|
+
1. `STORAGE_PROJECT`
|
|
79
|
+
2. `GOOGLE_CLOUD_PROJECT`
|
|
80
|
+
|
|
81
|
+
The environment variables that Storage checks for credentials are configured on {Google::Cloud::Storage::Credentials}:
|
|
82
|
+
|
|
83
|
+
1. `STORAGE_CREDENTIALS` - Path to JSON file, or JSON contents
|
|
84
|
+
2. `STORAGE_KEYFILE` - Path to JSON file, or JSON contents
|
|
85
|
+
3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
|
|
86
|
+
4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
|
|
87
|
+
5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
|
|
88
|
+
|
|
89
|
+
```ruby
|
|
90
|
+
require "google/cloud/storage"
|
|
91
|
+
|
|
92
|
+
ENV["STORAGE_PROJECT"] = "my-project-id"
|
|
93
|
+
ENV["STORAGE_CREDENTIALS"] = "path/to/keyfile.json"
|
|
94
|
+
|
|
95
|
+
storage = Google::Cloud::Storage.new
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Configuration
|
|
99
|
+
|
|
100
|
+
The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
|
|
101
|
+
|
|
102
|
+
```ruby
|
|
103
|
+
require "google/cloud/storage"
|
|
104
|
+
|
|
105
|
+
Google::Cloud::Storage.configure do |config|
|
|
106
|
+
config.project_id = "my-project-id"
|
|
107
|
+
config.credentials = "path/to/keyfile.json"
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
storage = Google::Cloud::Storage.new
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Cloud SDK
|
|
114
|
+
|
|
115
|
+
This option allows for an easy way to authenticate during development. If
|
|
116
|
+
credentials are not provided in code or in environment variables, then Cloud SDK
|
|
117
|
+
credentials are discovered.
|
|
118
|
+
|
|
119
|
+
To configure your system for this, simply:
|
|
120
|
+
|
|
121
|
+
1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
|
|
122
|
+
2. Authenticate using OAuth 2.0 `$ gcloud auth login`
|
|
123
|
+
3. Write code as if already authenticated.
|
|
124
|
+
|
|
125
|
+
**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
|
|
126
|
+
*should* only be used during development.
|
|
127
|
+
|
|
128
|
+
[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
|
|
129
|
+
[dev-console]: https://console.cloud.google.com/project
|
|
130
|
+
|
|
131
|
+
[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
|
|
132
|
+
|
|
133
|
+
[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
|
|
134
|
+
[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
|
|
135
|
+
[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
|
|
136
|
+
|
|
137
|
+
## Creating a Service Account
|
|
138
|
+
|
|
139
|
+
Google Cloud requires a **Project ID** and **Service Account Credentials** to
|
|
140
|
+
connect to the APIs. You will use the **Project ID** and **JSON key file** to
|
|
141
|
+
connect to most services with google-cloud-storage.
|
|
142
|
+
|
|
143
|
+
If you are not running this client on Google Compute Engine, you need a Google
|
|
144
|
+
Developers service account.
|
|
145
|
+
|
|
146
|
+
1. Visit the [Google Developers Console][dev-console].
|
|
147
|
+
1. Create a new project or click on an existing project.
|
|
148
|
+
1. Activate the slide-out navigation tray and select **API Manager**. From
|
|
149
|
+
here, you will enable the APIs that your application requires.
|
|
150
|
+
|
|
151
|
+
![Enable the APIs that your application requires][enable-apis]
|
|
152
|
+
|
|
153
|
+
*Note: You may need to enable billing in order to use these services.*
|
|
154
|
+
|
|
155
|
+
1. Select **Credentials** from the side navigation.
|
|
156
|
+
|
|
157
|
+
You should see a screen like one of the following.
|
|
158
|
+
|
|
159
|
+
![Create a new service account][create-new-service-account]
|
|
160
|
+
|
|
161
|
+
![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
|
|
162
|
+
|
|
163
|
+
Find the "Add credentials" drop down and select "Service account" to be
|
|
164
|
+
guided through downloading a new JSON key file.
|
|
165
|
+
|
|
166
|
+
If you want to re-use an existing service account, you can easily generate a
|
|
167
|
+
new key file. Just select the account you wish to re-use, and click "Generate
|
|
168
|
+
new JSON key":
|
|
169
|
+
|
|
170
|
+
![Re-use an existing service account][reuse-service-account]
|
|
171
|
+
|
|
172
|
+
The key file you download will be used by this library to authenticate API
|
|
173
|
+
requests and should be stored in a secure location.
|
|
174
|
+
|
|
175
|
+
## Troubleshooting
|
|
176
|
+
|
|
177
|
+
If you're having trouble authenticating you can ask for help by following the
|
|
178
|
+
{file:TROUBLESHOOTING.md Troubleshooting Guide}.
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# Release History
|
|
2
|
+
|
|
3
|
+
### 1.14.1 / 2018-09-12
|
|
4
|
+
|
|
5
|
+
* Add missing documentation files to package.
|
|
6
|
+
|
|
7
|
+
### 1.14.0 / 2018-09-10
|
|
8
|
+
|
|
9
|
+
* Add Object Lifecycle Management:
|
|
10
|
+
* Add Bucket#lifecycle.
|
|
11
|
+
* Add Bucket::Lifecycle and Bucket::Lifecycle::Rule.
|
|
12
|
+
* Update documentation.
|
|
13
|
+
|
|
14
|
+
### 1.13.1 / 2018-08-21
|
|
15
|
+
|
|
16
|
+
* Update documentation.
|
|
17
|
+
|
|
18
|
+
### 1.13.0 / 2018-06-22
|
|
19
|
+
|
|
20
|
+
* Update Policy, protect from role duplication.
|
|
21
|
+
* Updated dependencies.
|
|
22
|
+
|
|
23
|
+
### 1.12.0 / 2018-05-09
|
|
24
|
+
|
|
25
|
+
* Support Cloud KMS keys / Customer-managed encryption keys (CMEK).
|
|
26
|
+
|
|
27
|
+
### 1.11.0 / 2018-05-01
|
|
28
|
+
|
|
29
|
+
* Support partial Storage::File downloads. (georgeclaghorn)
|
|
30
|
+
* Add File#rewrite.
|
|
31
|
+
* Similar to File#copy, except for being able to specify both source and destination encryption keys.
|
|
32
|
+
* Refactor both File#copy and File#rotate to call File#rewrite.
|
|
33
|
+
* Update documentation for File-like IO parameters. The underlying libraries call #size on the argument, which is not present on IO, but is present on File and StringIO.
|
|
34
|
+
|
|
35
|
+
### 1.10.0 / 2018-02-27
|
|
36
|
+
|
|
37
|
+
* Support Shared Configuration.
|
|
38
|
+
* Fix verification for gzipped files.
|
|
39
|
+
* Add skip_decompress to File#download
|
|
40
|
+
* Update documentation and examples for gzip-encoded files.
|
|
41
|
+
* Fix issue with IAM Policy not refreshing properly.
|
|
42
|
+
* Update Google API Client dependency.
|
|
43
|
+
* Update authentication documentation
|
|
44
|
+
|
|
45
|
+
### 1.9.0 / 2017-11-20
|
|
46
|
+
|
|
47
|
+
* Add `Google::Cloud::Storage.anonymous` to support public data access.
|
|
48
|
+
|
|
49
|
+
### 1.8.0 / 2017-11-14
|
|
50
|
+
|
|
51
|
+
* Add `Google::Cloud::Storage::Credentials` class.
|
|
52
|
+
* Rename constructor arguments to `project_id` and `credentials`.
|
|
53
|
+
(The previous arguments `project` and `keyfile` are still supported.)
|
|
54
|
+
* Document `Google::Auth::Credentials` as `credentials` value.
|
|
55
|
+
* Updated `google-api-client`, `googleauth` dependencies.
|
|
56
|
+
|
|
57
|
+
### 1.7.1 / 2017-10-24
|
|
58
|
+
|
|
59
|
+
* Fix bug in Bucket#create_file, Bucket#compose, File#copy and File#rotate in
|
|
60
|
+
which user_project was not set on returned File object.
|
|
61
|
+
* Fix bug in Bucket::Acl#add_reader and Bucket::Acl#add_owner in which
|
|
62
|
+
user_project was not passed in the API request.
|
|
63
|
+
|
|
64
|
+
### 1.7.0 / 2017-10-18
|
|
65
|
+
|
|
66
|
+
* Add `Bucket#compose`.
|
|
67
|
+
* Update documentation.
|
|
68
|
+
|
|
69
|
+
### 1.6.0 / 2017-09-28
|
|
70
|
+
|
|
71
|
+
* Add `user_project` option to `Project#buckets` and `Project#create_bucket`.
|
|
72
|
+
* Upgrade to Google API Client 0.14.2.
|
|
73
|
+
* Update documentation.
|
|
74
|
+
|
|
75
|
+
### 1.5.0 / 2017-09-26
|
|
76
|
+
|
|
77
|
+
* Add Pub/Sub notification subscriptions.
|
|
78
|
+
* Update `#signed_url` to support symbols (dimroc).
|
|
79
|
+
|
|
80
|
+
### 1.4.0 / 2017-08-02
|
|
81
|
+
|
|
82
|
+
* Add `skip_lookup` option for retrieving `Bucket` and `File` objects
|
|
83
|
+
without accessing the Storage API
|
|
84
|
+
* Add `Bucket#exists?` method
|
|
85
|
+
* Add `File#exists?` method
|
|
86
|
+
* Add `File#generations` method
|
|
87
|
+
* Add `generation` argument to `File#delete`
|
|
88
|
+
* Add `generation` argument to `File#reload!`
|
|
89
|
+
* Add `Bucket#storage_class=` method
|
|
90
|
+
* Fix for when the `user_project` value set on a `Bucket` was not being
|
|
91
|
+
properly set on all `File` objects returned by `Bucket`.
|
|
92
|
+
* Fix to use `user_project` value when reloading a `Bucket`.
|
|
93
|
+
|
|
94
|
+
### 1.3.0 / 2017-07-11
|
|
95
|
+
|
|
96
|
+
* Add `query` parameter to `#signed_url` methods (georgeclaghorn).
|
|
97
|
+
|
|
98
|
+
### 1.2.0 / 2017-06-27
|
|
99
|
+
|
|
100
|
+
* Add Requester Pays support.
|
|
101
|
+
* Upgrade dependency on Google API Client.
|
|
102
|
+
|
|
103
|
+
### 1.1.0 / 2017-06-01
|
|
104
|
+
|
|
105
|
+
* Add Bucket#labels.
|
|
106
|
+
* Update gem spec homepage links.
|
|
107
|
+
* Remove memoization of Policy.
|
|
108
|
+
* Deprecate force parameter in Bucket#policy. (Will be removed in a future version.)
|
|
109
|
+
* Deprecate Policy#deep_dup. (Will be removed in a future version.)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
### 1.0.1 / 2017-04-10
|
|
113
|
+
|
|
114
|
+
* Add Bucket IAM support
|
|
115
|
+
|
|
116
|
+
### 1.0.0 / 2017-04-05
|
|
117
|
+
|
|
118
|
+
* Release 1.0
|
|
119
|
+
* Improvements to File copy for large files
|
|
120
|
+
* Allow file attributes to be changed during copy
|
|
121
|
+
* Upgrade dependency on Google API Client
|
|
122
|
+
|
|
123
|
+
### 0.25.0 / 2017-03-31
|
|
124
|
+
|
|
125
|
+
* Allow upload and download of in-memory IO objects
|
|
126
|
+
* Added signed_url at top-level object, without creating a bucket or file object
|
|
127
|
+
* Updated documentation
|
|
128
|
+
|
|
129
|
+
### 0.24.0 / 2017-03-03
|
|
130
|
+
|
|
131
|
+
* Dependency on Google API Client has been updated to 0.10.x.
|
|
132
|
+
|
|
133
|
+
### 0.23.2 / 2017-02-21
|
|
134
|
+
|
|
135
|
+
* Allow setting a File's storage_class on file creation
|
|
136
|
+
* Allow updating an existing File's storage_class
|
|
137
|
+
* Add File#rotate to rotate encryption keys
|
|
138
|
+
* Add PostObject and Bucket#post_object for uploading via HTML forms
|
|
139
|
+
|
|
140
|
+
### 0.23.1 / 2016-12-12
|
|
141
|
+
|
|
142
|
+
* Support Google extension headers on signed URLs (calavera)
|
|
143
|
+
|
|
144
|
+
### 0.23.0 / 2016-12-8
|
|
145
|
+
|
|
146
|
+
* Remove `encryption_key_sha256` method parameter, hash will be calculated using `encryption_key`
|
|
147
|
+
* Many documentation improvements
|
|
148
|
+
|
|
149
|
+
### 0.21.0 / 2016-10-20
|
|
150
|
+
|
|
151
|
+
* New service constructor Google::Cloud::Storage.new
|
|
152
|
+
* Bucket#signed_url added to create URLs without a File object
|
|
153
|
+
|
|
154
|
+
### 0.20.2 / 2016-09-30
|
|
155
|
+
|
|
156
|
+
* Fix issue with signed_url and file names with spaces (gsbucks)
|
|
157
|
+
|
|
158
|
+
### 0.20.1 / 2016-09-02
|
|
159
|
+
|
|
160
|
+
* Fix for timeout on uploads.
|
|
161
|
+
|
|
162
|
+
### 0.20.0 / 2016-08-26
|
|
163
|
+
|
|
164
|
+
This gem contains the Google Cloud Storage service implementation for the `google-cloud` gem. The `google-cloud` gem replaces the old `gcloud` gem. Legacy code can continue to use the `gcloud` gem.
|
|
165
|
+
|
|
166
|
+
* Namespace is now `Google::Cloud`
|
|
167
|
+
* The `google-cloud` gem is now an umbrella package for individual gems
|
data/CODE_OF_CONDUCT.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Contributor Code of Conduct
|
|
2
|
+
|
|
3
|
+
As contributors and maintainers of this project, and in the interest of
|
|
4
|
+
fostering an open and welcoming community, we pledge to respect all people who
|
|
5
|
+
contribute through reporting issues, posting feature requests, updating
|
|
6
|
+
documentation, submitting pull requests or patches, and other activities.
|
|
7
|
+
|
|
8
|
+
We are committed to making participation in this project a harassment-free
|
|
9
|
+
experience for everyone, regardless of level of experience, gender, gender
|
|
10
|
+
identity and expression, sexual orientation, disability, personal appearance,
|
|
11
|
+
body size, race, ethnicity, age, religion, or nationality.
|
|
12
|
+
|
|
13
|
+
Examples of unacceptable behavior by participants include:
|
|
14
|
+
|
|
15
|
+
* The use of sexualized language or imagery
|
|
16
|
+
* Personal attacks
|
|
17
|
+
* Trolling or insulting/derogatory comments
|
|
18
|
+
* Public or private harassment
|
|
19
|
+
* Publishing other's private information, such as physical or electronic
|
|
20
|
+
addresses, without explicit permission
|
|
21
|
+
* Other unethical or unprofessional conduct.
|
|
22
|
+
|
|
23
|
+
Project maintainers have the right and responsibility to remove, edit, or reject
|
|
24
|
+
comments, commits, code, wiki edits, issues, and other contributions that are
|
|
25
|
+
not aligned to this Code of Conduct. By adopting this Code of Conduct, project
|
|
26
|
+
maintainers commit themselves to fairly and consistently applying these
|
|
27
|
+
principles to every aspect of managing this project. Project maintainers who do
|
|
28
|
+
not follow or enforce the Code of Conduct may be permanently removed from the
|
|
29
|
+
project team.
|
|
30
|
+
|
|
31
|
+
This code of conduct applies both within project spaces and in public spaces
|
|
32
|
+
when an individual is representing the project or its community.
|
|
33
|
+
|
|
34
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
|
35
|
+
reported by opening an issue or contacting one or more of the project
|
|
36
|
+
maintainers.
|
|
37
|
+
|
|
38
|
+
This Code of Conduct is adapted from the [Contributor
|
|
39
|
+
Covenant](http://contributor-covenant.org), version 1.2.0, available at
|
|
40
|
+
[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
|
data/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# Contributing to Google Cloud Storage
|
|
2
|
+
|
|
3
|
+
1. **Sign one of the contributor license agreements below.**
|
|
4
|
+
2. Fork the repo, develop and test your code changes.
|
|
5
|
+
3. Send a pull request.
|
|
6
|
+
|
|
7
|
+
## Contributor License Agreements
|
|
8
|
+
|
|
9
|
+
Before we can accept your pull requests you'll need to sign a Contributor
|
|
10
|
+
License Agreement (CLA):
|
|
11
|
+
|
|
12
|
+
- **If you are an individual writing original source code** and **you own the
|
|
13
|
+
intellectual property**, then you'll need to sign an [individual
|
|
14
|
+
CLA](https://developers.google.com/open-source/cla/individual).
|
|
15
|
+
- **If you work for a company that wants to allow you to contribute your work**,
|
|
16
|
+
then you'll need to sign a [corporate
|
|
17
|
+
CLA](https://developers.google.com/open-source/cla/corporate).
|
|
18
|
+
|
|
19
|
+
You can sign these electronically (just scroll to the bottom). After that, we'll
|
|
20
|
+
be able to accept your pull requests.
|
|
21
|
+
|
|
22
|
+
## Setup
|
|
23
|
+
|
|
24
|
+
In order to use the google-cloud-storage console and run the project's tests,
|
|
25
|
+
there is a small amount of setup:
|
|
26
|
+
|
|
27
|
+
1. Install Ruby. google-cloud-storage requires Ruby 2.3+. You may choose to
|
|
28
|
+
manage your Ruby and gem installations with [RVM](https://rvm.io/),
|
|
29
|
+
[rbenv](https://github.com/rbenv/rbenv), or
|
|
30
|
+
[chruby](https://github.com/postmodern/chruby).
|
|
31
|
+
|
|
32
|
+
2. Install [Bundler](http://bundler.io/).
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
$ gem install bundler
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
3. Install the top-level project dependencies.
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
$ bundle install
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
4. Install the Storage dependencies.
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
$ cd google-cloud-storage/
|
|
48
|
+
$ bundle exec rake bundleupdate
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Console
|
|
52
|
+
|
|
53
|
+
In order to run code interactively, you can automatically load
|
|
54
|
+
google-cloud-storage and its dependencies in IRB. This requires that your
|
|
55
|
+
developer environment has already been configured by following the steps
|
|
56
|
+
described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
|
|
57
|
+
can be created with:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
$ cd google-cloud-storage/
|
|
61
|
+
$ bundle exec rake console
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Storage Tests
|
|
65
|
+
|
|
66
|
+
Tests are very important part of google-cloud-storage. All contributions
|
|
67
|
+
should include tests that ensure the contributed code behaves as expected.
|
|
68
|
+
|
|
69
|
+
To run the unit tests, documentation tests, and code style checks together for a
|
|
70
|
+
package:
|
|
71
|
+
|
|
72
|
+
``` sh
|
|
73
|
+
$ cd google-cloud-storage/
|
|
74
|
+
$ bundle exec rake ci
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
|
|
78
|
+
its handy alias, `rake ci:a`.
|
|
79
|
+
|
|
80
|
+
### Storage Unit Tests
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
The project uses the [minitest](https://github.com/seattlerb/minitest) library,
|
|
84
|
+
including [specs](https://github.com/seattlerb/minitest#specs),
|
|
85
|
+
[mocks](https://github.com/seattlerb/minitest#mocks) and
|
|
86
|
+
[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
|
|
87
|
+
|
|
88
|
+
To run the Storage unit tests:
|
|
89
|
+
|
|
90
|
+
``` sh
|
|
91
|
+
$ cd google-cloud-storage/
|
|
92
|
+
$ bundle exec rake test
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Storage Documentation Tests
|
|
96
|
+
|
|
97
|
+
The project tests the code examples in the gem's
|
|
98
|
+
[YARD](https://github.com/lsegal/yard)-based documentation.
|
|
99
|
+
|
|
100
|
+
The example testing functions in a way that is very similar to unit testing, and
|
|
101
|
+
in fact the library providing it,
|
|
102
|
+
[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
|
|
103
|
+
project's unit test library, [minitest](https://github.com/seattlerb/minitest).
|
|
104
|
+
|
|
105
|
+
To run the Storage documentation tests:
|
|
106
|
+
|
|
107
|
+
``` sh
|
|
108
|
+
$ cd google-cloud-storage/
|
|
109
|
+
$ bundle exec rake doctest
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
If you add, remove or modify documentation examples when working on a pull
|
|
113
|
+
request, you may need to update the setup for the tests. The stubs and mocks
|
|
114
|
+
required to run the tests are located in `support/doctest_helper.rb`. Please
|
|
115
|
+
note that much of the setup is matched by the title of the
|
|
116
|
+
[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
|
|
117
|
+
If you alter an example's title, you may encounter breaking tests.
|
|
118
|
+
|
|
119
|
+
### Storage Acceptance Tests
|
|
120
|
+
|
|
121
|
+
The Storage acceptance tests interact with the live service API. Follow the
|
|
122
|
+
instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
|
|
123
|
+
the Storage API. Occasionally, some API features may not yet be generally
|
|
124
|
+
available, making it difficult for some contributors to successfully run the
|
|
125
|
+
entire acceptance test suite. However, please ensure that you do successfully
|
|
126
|
+
run acceptance tests for any code areas covered by your pull request.
|
|
127
|
+
|
|
128
|
+
To run the acceptance tests, first create and configure a project in the Google
|
|
129
|
+
Developers Console, as described in the {file:AUTHENTICATION.md Authentication
|
|
130
|
+
guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
|
|
131
|
+
the KEYFILE location on your system.
|
|
132
|
+
|
|
133
|
+
Before you can run the Storage acceptance tests, you must first create indexes
|
|
134
|
+
used in the tests.
|
|
135
|
+
|
|
136
|
+
#### Running the Storage acceptance tests
|
|
137
|
+
|
|
138
|
+
To run the Storage acceptance tests:
|
|
139
|
+
|
|
140
|
+
``` sh
|
|
141
|
+
$ cd google-cloud-storage/
|
|
142
|
+
$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
|
|
146
|
+
`GCLOUD_TEST_KEYFILE` environment variables:
|
|
147
|
+
|
|
148
|
+
``` sh
|
|
149
|
+
$ cd google-cloud-storage/
|
|
150
|
+
$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
|
|
151
|
+
$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
|
|
152
|
+
$ bundle exec rake acceptance
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
If you want to use a different project and credentials for acceptance tests, you
|
|
156
|
+
can use the more specific `STORAGE_TEST_PROJECT` and `STORAGE_TEST_KEYFILE`
|
|
157
|
+
environment variables:
|
|
158
|
+
|
|
159
|
+
``` sh
|
|
160
|
+
$ cd google-cloud-storage/
|
|
161
|
+
$ export STORAGE_TEST_PROJECT=\\{my-project-id}
|
|
162
|
+
$ export STORAGE_TEST_KEYFILE=\\{/path/to/keyfile.json}
|
|
163
|
+
$ bundle exec rake acceptance
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Coding Style
|
|
167
|
+
|
|
168
|
+
Please follow the established coding style in the library. The style is is
|
|
169
|
+
largely based on [The Ruby Style
|
|
170
|
+
Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
|
|
171
|
+
on seattle-style:
|
|
172
|
+
|
|
173
|
+
* Avoid parenthesis when possible, including in method definitions.
|
|
174
|
+
* Always use double quotes strings. ([Option
|
|
175
|
+
B](https://github.com/bbatsov/ruby-style-guide#strings))
|
|
176
|
+
|
|
177
|
+
You can check your code against these rules by running Rubocop like so:
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
$ cd google-cloud-storage/
|
|
181
|
+
$ bundle exec rake rubocop
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Code of Conduct
|
|
185
|
+
|
|
186
|
+
Please note that this project is released with a Contributor Code of Conduct. By
|
|
187
|
+
participating in this project you agree to abide by its terms. See
|
|
188
|
+
{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
|