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 (at] 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 (at] google.com as a reviewer, and Cc gs-team (at] 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 ) 149
