OLD | NEW |
| (Empty) |
1 # -*- coding: utf-8 -*- | |
2 # Copyright 2012 Google Inc. All Rights Reserved. | |
3 # | |
4 # Licensed under the Apache License, Version 2.0 (the "License"); | |
5 # you may not use this file except in compliance with the License. | |
6 # You may obtain a copy of the License at | |
7 # | |
8 # http://www.apache.org/licenses/LICENSE-2.0 | |
9 # | |
10 # Unless required by applicable law or agreed to in writing, software | |
11 # distributed under the License is distributed on an "AS IS" BASIS, | |
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
13 # See the License for the specific language governing permissions and | |
14 # limitations under the License. | |
15 """Additional help about contributing code to gsutil.""" | |
16 | |
17 from __future__ import absolute_import | |
18 | |
19 from gslib.help_provider import HelpProvider | |
20 | |
21 _DETAILED_HELP_TEXT = (""" | |
22 <B>OVERVIEW</B> | |
23 We're open to incorporating gsutil code changes authored by users. Here | |
24 are some guidelines: | |
25 | |
26 1. Before we can accept code submissions, we have to jump a couple of legal | |
27 hurdles. Please fill out either the individual or corporate Contributor | |
28 License Agreement: | |
29 | |
30 - If you are an individual writing original source code and you're | |
31 sure you own the intellectual property, | |
32 then you'll need to sign an individual CLA | |
33 (https://cla.developers.google.com/about/google-individual). | |
34 - If you work for a company that wants to allow you to contribute your | |
35 work to gsutil, then you'll need to sign a corporate CLA | |
36 (https://cla.developers.google.com/about/google-corporate) | |
37 | |
38 Follow either of the two links above to access the appropriate CLA and | |
39 instructions for how to sign and return it. Once we receive it, we'll | |
40 add you to the official list of contributors and be able to accept | |
41 your patches. | |
42 | |
43 2. If you found a bug or have an idea for a feature enhancement, we suggest | |
44 you check https://github.com/GoogleCloudPlatform/gsutil/issues to see if it | |
45 has already been reported by another user. From there you can also | |
46 subscribe to updates to the issue by clicking the "Watch thread" button at | |
47 the bottom of the page. | |
48 | |
49 3. It's usually worthwhile to send email to gs-team@google.com about your | |
50 idea before sending actual code. Often we can discuss the idea and help | |
51 propose things that could save you later revision work. | |
52 | |
53 4. We tend to avoid adding command line options that are of use to only | |
54 a very small fraction of users, especially if there's some other way | |
55 to accommodate such needs. Adding such options complicates the code and | |
56 also adds overhead to users having to read through an "alphabet soup" | |
57 list of option documentation. | |
58 | |
59 5. While gsutil has a number of features specific to Google Cloud Storage, | |
60 it can also be used with other cloud storage providers. We're open to | |
61 including changes for making gsutil support features specific to other | |
62 providers, as long as those changes don't make gsutil work worse for Google | |
63 Cloud Storage. If you do make such changes we recommend including someone | |
64 with knowledge of the specific provider as a code reviewer (see below). | |
65 | |
66 6. You can check out the gsutil code from the GitHub repository: | |
67 | |
68 https://github.com/GoogleCloudPlatform/gsutil | |
69 | |
70 To clone a read-only copy of the repository: | |
71 | |
72 git clone git://github.com/GoogleCloudPlatform/gsutil.git | |
73 git submodule update --init --recursive | |
74 | |
75 To push your own changes to GitHub, click the Fork button on the | |
76 repository page and clone the repository from your own fork. | |
77 | |
78 7. The gsutil git repository uses git submodules to pull in external modules. | |
79 After checking out the repository, make sure to also pull the submodules | |
80 by entering into the gsutil top-level directory and run: | |
81 | |
82 git submodule update --init --recursive | |
83 | |
84 8. Please make sure to run all tests against your modified code. To | |
85 do this, change directories into the gsutil top-level directory and run: | |
86 | |
87 ./gsutil test | |
88 | |
89 The above tests take a long time to run because they send many requests to | |
90 the production service. The gsutil test command has a -u argument that will | |
91 only run unit tests. These run quickly, as they are executed with an | |
92 in-memory mock storage service implementation. To run only the unit tests, | |
93 run: | |
94 | |
95 ./gsutil test -u | |
96 | |
97 If you made changes to boto, please run the boto tests. For these tests you | |
98 need to use HMAC credentials (from gsutil config -a), because the current | |
99 boto test suite doesn't import the OAuth2 handler. You'll also need to | |
100 install some python modules. Change directories into the boto root | |
101 directory at third_party/boto and run: | |
102 | |
103 pip install -r requirements.txt | |
104 | |
105 (You probably need to run this command using sudo.) | |
106 Make sure each of the individual installations succeeded. If they don't | |
107 you may need to run the install command again. | |
108 | |
109 Then ensure your .boto file has HMAC credentials defined (the boto tests | |
110 don't load the OAUTH2 plugin), and then change directories into boto's | |
111 tests directory and run: | |
112 | |
113 python test.py unit | |
114 python test.py -t s3 -t gs -t ssl | |
115 | |
116 9. Please consider contributing test code for your change, especially if the | |
117 change impacts any of the core gsutil code (like the gsutil cp command). | |
118 | |
119 10. When it's time to send us code, please use the Rietveld code review tool | |
120 rather than simply sending us a code patch. Do this as follows: | |
121 | |
122 - Check out the gsutil code from your fork of the gsutil repository and | |
123 apply your changes. | |
124 - Download the "upload.py" script from | |
125 https://github.com/rietveld-codereview/rietveld | |
126 - Run upload.py from your git directory with the changes. | |
127 - Click the codereview.appspot.com link it generates, click "Edit Issue", | |
128 and add mfschwartz@google.com as a reviewer, and Cc gs-team@google.com. | |
129 - Click Publish+Mail Comments. | |
130 - Once your changes are accepted, submit a pull request on GitHub and we | |
131 will merge your commits. | |
132 """) | |
133 | |
134 | |
135 class CommandOptions(HelpProvider): | |
136 """Additional help about contributing code to gsutil.""" | |
137 # TODO: gsutil-beta: Add lint .rc file and linting instructions. | |
138 | |
139 # Help specification. See help_provider.py for documentation. | |
140 help_spec = HelpProvider.HelpSpec( | |
141 help_name='dev', | |
142 help_name_aliases=[ | |
143 'development', 'developer', 'code', 'mods', 'software'], | |
144 help_type='additional_help', | |
145 help_one_line_summary='Contributing Code to gsutil', | |
146 help_text=_DETAILED_HELP_TEXT, | |
147 subcommand_help_text={}, | |
148 ) | |
OLD | NEW |