OLD | NEW |
| (Empty) |
1 # Copyright 2012 Google Inc. All Rights Reserved. | |
2 # | |
3 # Licensed under the Apache License, Version 2.0 (the "License"); | |
4 # you may not use this file except in compliance with the License. | |
5 # You may obtain a copy of the License at | |
6 # | |
7 # http://www.apache.org/licenses/LICENSE-2.0 | |
8 # | |
9 # Unless required by applicable law or agreed to in writing, software | |
10 # distributed under the License is distributed on an "AS IS" BASIS, | |
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 # See the License for the specific language governing permissions and | |
13 # limitations under the License. | |
14 | |
15 from gslib.help_provider import HELP_NAME | |
16 from gslib.help_provider import HELP_NAME_ALIASES | |
17 from gslib.help_provider import HELP_ONE_LINE_SUMMARY | |
18 from gslib.help_provider import HelpProvider | |
19 from gslib.help_provider import HELP_TEXT | |
20 from gslib.help_provider import HelpType | |
21 from gslib.help_provider import HELP_TYPE | |
22 | |
23 _detailed_help_text = (""" | |
24 <B>OVERVIEW</B> | |
25 We're open to incorporating gsutil code changes authored by users. Here | |
26 are some guidelines: | |
27 | |
28 1. Before we can accept code submissions, we have to jump a couple of legal | |
29 hurdles. Please fill out either the individual or corporate Contributor | |
30 License Agreement: | |
31 - If you are an individual writing original source code and you're | |
32 sure you own the intellectual property, | |
33 then you'll need to sign an individual CLA | |
34 (http://code.google.com/legal/individual-cla-v1.0.html). | |
35 - If you work for a company that wants to allow you to contribute your | |
36 work to gsutil, then you'll need to sign a corporate CLA | |
37 (http://code.google.com/legal/corporate-cla-v1.0.html) | |
38 | |
39 Follow either of the two links above to access the appropriate CLA and | |
40 instructions for how to sign and return it. Once we receive it, we'll | |
41 add you to the official list of contributors and be able to accept | |
42 your patches. | |
43 | |
44 2. If you found a bug or have an idea for a feature enhancement, we suggest | |
45 you check http://code.google.com/p/gsutil/issues/list to see if it has | |
46 already been reported by another user. From there you can also add yourself | |
47 to the Cc list for an issue, so you will find out about any developments. | |
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 svn - see | |
67 http://code.google.com/p/gsutil/source/checkout. Then change directories | |
68 into gsutil/src, and check out the boto code from github: | |
69 | |
70 git clone git://github.com/boto/boto.git | |
71 | |
72 7. Please make sure to run all tests against your modified code. To | |
73 do this, change directories into the gsutil top-level directory and run: | |
74 | |
75 ./gsutil test | |
76 | |
77 The above tests take a long time to run because they send many requests to | |
78 the production service. The gsutil test command has a -u argument that will | |
79 only run unit tests. These run quickly, as they are executed with an | |
80 in-memory mock storage service implementation. To run only the unit tests, | |
81 run: | |
82 | |
83 ./gsutil test -u | |
84 | |
85 If you made mods to boto please run the boto tests. For these tests you | |
86 need to use HMAC credentials (from gsutil config -a), because the current | |
87 boto test suite doesn't import the OAuth2 handler. You'll also need to | |
88 install some python modules: change directories into the top-level gsutil | |
89 directory and run: | |
90 | |
91 pip install -qr boto/requirements.txt | |
92 | |
93 (You probably need to run this commad using sudo.) | |
94 Make sure each of the individual installations succeeded. If they don't | |
95 you may need to run individual ones again, e.g., | |
96 | |
97 pip install unittest2 | |
98 | |
99 Then ensure your .boto file has HMAC credentials defined (the boto tests | |
100 don't load the OAUTH2 plugin), and then change directories into boto/tests | |
101 and run: | |
102 | |
103 python test.py unit | |
104 python test.py -t s3 -t gs -t ssl | |
105 | |
106 8. Please consider contributing test code for your change, especially if the | |
107 change impacts any of the core gsutil code (like the gsutil cp command). | |
108 | |
109 9. When it's time to send us code, please use the Rietveld code review tool | |
110 rather than simply sending us a code patch. Do this as follows: | |
111 - check out the gsutil code from at | |
112 http://code.google.com/p/gsutil/source/checkout and apply your changes | |
113 in the checked out directory. | |
114 - download the "upload.py" script from | |
115 http://code.google.com/p/rietveld/wiki/UploadPyUsage | |
116 - run upload.py from the above gsutil svn directory. | |
117 - click the codereview.appspot.com link it generates, click "Edit Issue", | |
118 and add mfschwartz@google.com as a reviewer, and Cc gs-team@google.com. | |
119 - click Publish+Mail Comments. | |
120 """) | |
121 | |
122 | |
123 | |
124 class CommandOptions(HelpProvider): | |
125 """Additional help about Access Control Lists.""" | |
126 | |
127 help_spec = { | |
128 # Name of command or auxiliary help info for which this help applies. | |
129 HELP_NAME : 'dev', | |
130 # List of help name aliases. | |
131 HELP_NAME_ALIASES : ['development', 'developer', 'code', 'mods', | |
132 'software'], | |
133 # Type of help: | |
134 HELP_TYPE : HelpType.ADDITIONAL_HELP, | |
135 # One line summary of this help. | |
136 HELP_ONE_LINE_SUMMARY : 'Making modifications to gsutil', | |
137 # The full help text. | |
138 HELP_TEXT : _detailed_help_text, | |
139 } | |
OLD | NEW |