| 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 |