mirror of
https://github.com/kennethreitz/requests.git
synced 2026-06-05 22:50:18 +00:00
Merge pull request #2572 from Lukasa/contribution
Add basic contributing guide
This commit is contained in:
@@ -0,0 +1,161 @@
|
||||
.. _contributing:
|
||||
|
||||
Contributor's Guide
|
||||
===================
|
||||
|
||||
If you're reading this you're probably interested in contributing to
|
||||
``requests``. First, I'd like to say: thankyou! Open source projects
|
||||
live-and-die based on the support they receive from others, and the fact that
|
||||
you're even *considering* supporting ``requests`` is incredibly generous of
|
||||
you.
|
||||
|
||||
This document lays out guidelines and advice for contributing to ``requests``.
|
||||
If you're thinking of contributing, start by reading this thoroughly and
|
||||
getting a feel for how contributing to the project works. If you've still got
|
||||
questions after reading this, you should go ahead and contact either
|
||||
`Ian Cordasco`_ or `Cory Benfield`_, the active maintainers.
|
||||
|
||||
The guide is split into sections based on the type of contribution you're
|
||||
thinking of making, with a section that covers general guidelines for all
|
||||
contributors.
|
||||
|
||||
.. _Ian Cordasco: http://www.coglib.com/~icordasc/
|
||||
.. _Cory Benfield: https://lukasa.co.uk/about
|
||||
|
||||
|
||||
All Contributions
|
||||
-----------------
|
||||
|
||||
Be Cordial Or Be On Your Way
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
``requests`` has one very important guideline governing all forms of
|
||||
contribution, including things like reporting bugs or requesting features. The
|
||||
guideline is `be cordial or be on your way`_. **All contributions are
|
||||
welcome**, but they come with an implicit social contract: everyone must be
|
||||
treated with respect.
|
||||
|
||||
This can be a difficult area to judge, so the maintainers will enforce the
|
||||
following policy. If any contributor acts rudely or aggressively towards any
|
||||
other contributor, **regardless of whether they perceive themselves to be
|
||||
acting in retaliation for an earlier breach of this guideline**, they will be
|
||||
subject to the following procedure:
|
||||
|
||||
1. They must apologise. This apology must be genuine in nature: "I'm sorry you
|
||||
were offended" is not sufficient. The judgement of 'genuine' is at the
|
||||
discretion of the maintainers.
|
||||
2. If the apology is not offered, any outstanding and future contributions from
|
||||
the violating contributor will be rejected immediately.
|
||||
|
||||
Everyone involved in the ``requests`` project, the maintainers included, are
|
||||
bound by this policy. Failing to abide by it leads to the offender being kicked
|
||||
off the project.
|
||||
|
||||
.. _be cordial or be on your way: http://kennethreitz.org/be-cordial-or-be-on-your-way/
|
||||
|
||||
.. _early-feedback:
|
||||
|
||||
Get Early Feedback
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you are contributing, do not feel the need to sit on your contribution until
|
||||
it is perfectly polished and complete. It helps everyone involved for you to
|
||||
seek feedback as early as you possibly can. Submitting an early, unfinished
|
||||
version of your contribution for feedback in no way prejudices your chances of
|
||||
getting that contribution accepted, and can save you from putting a lot of work
|
||||
into a contribution that is not suitable for the project.
|
||||
|
||||
Contribution Suitability
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The project maintainer has the last word on whether or not a contribution is
|
||||
suitable for ``requests``. All contributions will be considered, but from time
|
||||
to time contributions will be rejected because they do not suit the project.
|
||||
|
||||
If your contribution is rejected, don't despair! So long as you followed these
|
||||
guidelines, you'll have a much better chance of getting your next contribution
|
||||
accepted.
|
||||
|
||||
|
||||
Code Contributions
|
||||
------------------
|
||||
|
||||
Steps
|
||||
~~~~~
|
||||
|
||||
When contributing code, you'll want to follow this checklist:
|
||||
|
||||
1. Fork the repository on GitHub.
|
||||
2. Run the tests to confirm they all pass on your system. If they don't, you'll
|
||||
need to investigate why they fail. If you're unable to diagnose this
|
||||
yourself, raise it as a bug report by following the guidelines in this
|
||||
document: :ref:`bug-reports`.
|
||||
3. Write tests that demonstrate your bug or feature. Ensure that they fail.
|
||||
4. Make your change.
|
||||
5. Run the entire test suite again, confirming that all tests pass *including
|
||||
the ones you just added*.
|
||||
6. Send a GitHub Pull Request to the main repository's ``master`` branch.
|
||||
GitHub Pull Requests are the expected method of code collaboration on this
|
||||
project. If you object to the GitHub workflow, you may mail a patch to any
|
||||
of the maintainers listed above.
|
||||
|
||||
The following sub-sections go into more detail on some of the points above.
|
||||
|
||||
Code Review
|
||||
~~~~~~~~~~~
|
||||
|
||||
Contributions will not be merged until they've been code reviewed. You should
|
||||
implement any code review feedback unless you strongly object to it. In the
|
||||
event that you object to the code review feedback, you should make your case
|
||||
clearly and calmly. If, after doing so, the feedback is judged to still apply,
|
||||
you must either apply the feedback or withdraw your contribution.
|
||||
|
||||
New Contributors
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
If you are new or relatively new to Open Source, welcome! ``requests`` aims to
|
||||
be a gentle introduction to the world of Open Source. If you're concerned about
|
||||
how best to contribute, please consider mailing a maintainer (listed above) and
|
||||
asking for help.
|
||||
|
||||
Please also check the :ref:`early-feedback` section.
|
||||
|
||||
Documentation Contributions
|
||||
---------------------------
|
||||
|
||||
Documentation improvements are always welcome! The documentation files live in
|
||||
the ``docs/`` directory of the codebase. They're written in
|
||||
`reStructuredText`_, and use `Sphinx`_ to generate the full suite of
|
||||
documentation.
|
||||
|
||||
When contributing documentation, please attempt to follow the style of the
|
||||
documentation files. This means a soft-limit of 79 characters wide in your text
|
||||
files and a semi-formal prose style.
|
||||
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
.. _Sphinx: http://sphinx-doc.org/index.html
|
||||
|
||||
|
||||
.. _bug-reports:
|
||||
|
||||
Bug Reports
|
||||
-----------
|
||||
|
||||
Bug reports are hugely important! Before you raise one, though, please check
|
||||
through the `GitHub issues`_, **both open and closed**, to confirm that the bug
|
||||
hasn't been reported before. Duplicate bug reports are a huge drain on the time
|
||||
of other contributors, and should be avoided as much as possible.
|
||||
|
||||
.. _GitHub issues: https://github.com/kennethreitz/requests/issues
|
||||
|
||||
|
||||
Feature Requests
|
||||
----------------
|
||||
|
||||
Requests is in a perpeptual feature freeze. The maintainers believe that
|
||||
requests contains every major feature currently required by the vast majority
|
||||
of users.
|
||||
|
||||
If you believe there is a feature missing, feel free to raise a feature
|
||||
request, but please do be aware that the overwhelming likelihood is that your
|
||||
feature request will not be accepted.
|
||||
@@ -141,6 +141,7 @@ you.
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
dev/contributing
|
||||
dev/philosophy
|
||||
dev/todo
|
||||
dev/authors
|
||||
|
||||
Reference in New Issue
Block a user