| OLD | NEW |
|---|
| (Empty) |
| 1 .. _contributing: | |
| 2 | |
| 3 Contributor's Guide | |
| 4 =================== | |
| 5 | |
| 6 If you're reading this, you're probably interested in contributing to Requests. | |
| 7 Thank you very much! Open source projects live-and-die based on the support | |
| 8 they receive from others, and the fact that you're even considering | |
| 9 contributing to the Requests project is *very* generous of you. | |
| 10 | |
| 11 This document lays out guidelines and advice for contributing to this project. | |
| 12 If you're thinking of contributing, please start by reading this document and | |
| 13 getting a feel for how contributing to this project works. If you have any | |
| 14 questions, feel free to reach out to either `Ian Cordasco`_ or `Cory Benfield`_, | |
| 15 the primary maintainers. | |
| 16 | |
| 17 .. _Ian Cordasco: http://www.coglib.com/~icordasc/ | |
| 18 .. _Cory Benfield: https://lukasa.co.uk/about | |
| 19 | |
| 20 If you have non-technical feedback, philosophical ponderings, crazy ideas, or | |
| 21 other general thoughts about Requests or its position within the Python | |
| 22 ecosystem, the BDFL, `Kenneth Reitz`_, would love to hear from you. | |
| 23 | |
| 24 The guide is split into sections based on the type of contribution you're | |
| 25 thinking of making, with a section that covers general guidelines for all | |
| 26 contributors. | |
| 27 | |
| 28 .. _Kenneth Reitz: mailto:me@kennethreitz.org | |
| 29 | |
| 30 Be Cordial | |
| 31 ---------- | |
| 32 | |
| 33 **Be cordial or be on your way**. *—Kenneth Reitz* | |
| 34 | |
| 35 Requests has one very important rule governing all forms of contribution, | |
| 36 including reporting bugs or requesting features. This golden rule is | |
| 37 "`be cordial or be on your way`_". | |
| 38 | |
| 39 **All contributions are welcome**, as long as | |
| 40 everyone involved is treated with respect. | |
| 41 | |
| 42 .. _be cordial or be on your way: http://kennethreitz.org/be-cordial-or-be-on-yo
ur-way/ | |
| 43 | |
| 44 .. _early-feedback: | |
| 45 | |
| 46 Get Early Feedback | |
| 47 ------------------ | |
| 48 | |
| 49 If you are contributing, do not feel the need to sit on your contribution until | |
| 50 it is perfectly polished and complete. It helps everyone involved for you to | |
| 51 seek feedback as early as you possibly can. Submitting an early, unfinished | |
| 52 version of your contribution for feedback in no way prejudices your chances of | |
| 53 getting that contribution accepted, and can save you from putting a lot of work | |
| 54 into a contribution that is not suitable for the project. | |
| 55 | |
| 56 Contribution Suitability | |
| 57 ------------------------ | |
| 58 | |
| 59 Our project maintainers have the last word on whether or not a contribution is | |
| 60 suitable for Requests. All contributions will be considered carefully, but from | |
| 61 time to time, contributions will be rejected because they do not suit the | |
| 62 current goals or needs of the project. | |
| 63 | |
| 64 If your contribution is rejected, don't despair! As long as you followed these | |
| 65 guidelines, you will have a much better chance of getting your next | |
| 66 contribution accepted. | |
| 67 | |
| 68 | |
| 69 Code Contributions | |
| 70 ------------------ | |
| 71 | |
| 72 Steps for Submitting Code | |
| 73 ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 74 | |
| 75 When contributing code, you'll want to follow this checklist: | |
| 76 | |
| 77 1. Fork the repository on GitHub. | |
| 78 2. Run the tests to confirm they all pass on your system. If they don't, you'll | |
| 79 need to investigate why they fail. If you're unable to diagnose this | |
| 80 yourself, raise it as a bug report by following the guidelines in this | |
| 81 document: :ref:`bug-reports`. | |
| 82 3. Write tests that demonstrate your bug or feature. Ensure that they fail. | |
| 83 4. Make your change. | |
| 84 5. Run the entire test suite again, confirming that all tests pass *including | |
| 85 the ones you just added*. | |
| 86 6. Send a GitHub Pull Request to the main repository's ``master`` branch. | |
| 87 GitHub Pull Requests are the expected method of code collaboration on this | |
| 88 project. | |
| 89 | |
| 90 The following sub-sections go into more detail on some of the points above. | |
| 91 | |
| 92 Code Review | |
| 93 ~~~~~~~~~~~ | |
| 94 | |
| 95 Contributions will not be merged until they've been code reviewed. You should | |
| 96 implement any code review feedback unless you strongly object to it. In the | |
| 97 event that you object to the code review feedback, you should make your case | |
| 98 clearly and calmly. If, after doing so, the feedback is judged to still apply, | |
| 99 you must either apply the feedback or withdraw your contribution. | |
| 100 | |
| 101 New Contributors | |
| 102 ~~~~~~~~~~~~~~~~ | |
| 103 | |
| 104 If you are new or relatively new to Open Source, welcome! Requests aims to | |
| 105 be a gentle introduction to the world of Open Source. If you're concerned about | |
| 106 how best to contribute, please consider mailing a maintainer (listed above) and | |
| 107 asking for help. | |
| 108 | |
| 109 Please also check the :ref:`early-feedback` section. | |
| 110 | |
| 111 Kenneth Reitz's Code Style™ | |
| 112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 113 | |
| 114 The Requests codebase uses the `PEP 8`_ code style. | |
| 115 | |
| 116 In addition to the standards outlined in PEP 8, we have a few guidelines: | |
| 117 | |
| 118 - Line-length can exceed 79 characters, to 100, when convenient. | |
| 119 - Line-length can exceed 100 characters, when doing otherwise would be *terribly
* inconvenient. | |
| 120 - Always use single-quoted strings (e.g. ``'#flatearth'``), unless a single-quot
e occurs within the string. | |
| 121 | |
| 122 Additionally, one of the styles that PEP8 recommends for `line continuations`_ | |
| 123 completely lacks all sense of taste, and is not to be permitted within | |
| 124 the Requests codebase:: | |
| 125 | |
| 126 # Aligned with opening delimiter. | |
| 127 foo = long_function_name(var_one, var_two, | |
| 128 var_three, var_four) | |
| 129 | |
| 130 No. Just don't. Please. | |
| 131 | |
| 132 Docstrings are to follow the following syntaxes:: | |
| 133 | |
| 134 def the_earth_is_flat(): | |
| 135 """NASA divided up the seas into thirty-three degrees.""" | |
| 136 pass | |
| 137 | |
| 138 :: | |
| 139 | |
| 140 def fibonacci_spiral_tool(): | |
| 141 """With my feet upon the ground I lose myself / between the sounds | |
| 142 and open wide to suck it in. / I feel it move across my skin. / I'm | |
| 143 reaching up and reaching out. / I'm reaching for the random or | |
| 144 whatever will bewilder me. / Whatever will bewilder me. / And | |
| 145 following our will and wind we may just go where no one's been. / | |
| 146 We'll ride the spiral to the end and may just go where no one's | |
| 147 been. | |
| 148 | |
| 149 Spiral out. Keep going... | |
| 150 """ | |
| 151 pass | |
| 152 | |
| 153 All functions, methods, and classes are to contain docstrings. Object data | |
| 154 model methods (e.g. ``__repr__``) are typically the exception to this rule. | |
| 155 | |
| 156 Thanks for helping to make the world a better place! | |
| 157 | |
| 158 .. _PEP 8: http://pep8.org | |
| 159 .. _line continuations: https://www.python.org/dev/peps/pep-0008/#indentation | |
| 160 | |
| 161 Documentation Contributions | |
| 162 --------------------------- | |
| 163 | |
| 164 Documentation improvements are always welcome! The documentation files live in | |
| 165 the ``docs/`` directory of the codebase. They're written in | |
| 166 `reStructuredText`_, and use `Sphinx`_ to generate the full suite of | |
| 167 documentation. | |
| 168 | |
| 169 When contributing documentation, please do your best to follow the style of the | |
| 170 documentation files. This means a soft-limit of 79 characters wide in your text | |
| 171 files and a semi-formal, yet friendly and approachable, prose style. | |
| 172 | |
| 173 When presenting Python code, use single-quoted strings (``'hello'`` instead of | |
| 174 ``"hello"``). | |
| 175 | |
| 176 .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
| 177 .. _Sphinx: http://sphinx-doc.org/index.html | |
| 178 | |
| 179 | |
| 180 .. _bug-reports: | |
| 181 | |
| 182 Bug Reports | |
| 183 ----------- | |
| 184 | |
| 185 Bug reports are hugely important! Before you raise one, though, please check | |
| 186 through the `GitHub issues`_, **both open and closed**, to confirm that the bug | |
| 187 hasn't been reported before. Duplicate bug reports are a huge drain on the time | |
| 188 of other contributors, and should be avoided as much as possible. | |
| 189 | |
| 190 .. _GitHub issues: https://github.com/kennethreitz/requests/issues | |
| 191 | |
| 192 | |
| 193 Feature Requests | |
| 194 ---------------- | |
| 195 | |
| 196 Requests is in a perpetual feature freeze, only the BDFL can add or approve of | |
| 197 new features. The maintainers believe that Requests is a feature-complete | |
| 198 piece of software at this time. | |
| 199 | |
| 200 One of the most important skills to have while maintaining a largely-used | |
| 201 open source project is learning the ability to say "no" to suggested changes, | |
| 202 while keeping an open ear and mind. | |
| 203 | |
| 204 If you believe there is a feature missing, feel free to raise a feature | |
| 205 request, but please do be aware that the overwhelming likelihood is that your | |
| 206 feature request will not be accepted. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2164713003:
Vendor requests. (Closed)
Base URL: https://chromium.googlesource.com/external/github.com/luci/recipes-py@master