mirror of
https://github.com/kennethreitz/pipenv.git
synced 2026-06-05 06:46:15 +00:00
Consolidate all contributing docs in the rst file
This commit is contained in:
Brianna Laugher
+2
-93
@@ -1,99 +1,8 @@
|
||||
# Contribution Guidelines
|
||||
# Contributing
|
||||
|
||||
Before opening any issues or proposing any pull requests, please do the
|
||||
following:
|
||||
Please see the [Contributing Guide](https://pipenv.readthedocs.io/en/latest/dev/contributing/).
|
||||
|
||||
1. Read our [Contributor's Guide](https://docs.pipenv.org/dev/contributing/).
|
||||
2. Understand our [development philosophy](https://docs.pipenv.org/dev/philosophy/).
|
||||
|
||||
To get the greatest chance of helpful responses, please also observe the
|
||||
following additional notes.
|
||||
|
||||
## Questions
|
||||
|
||||
The GitHub issue tracker is for *bug reports* and *feature requests*. Please do
|
||||
not use it to ask questions about how to use Pipenv. These questions should
|
||||
instead be directed to [Stack Overflow](https://stackoverflow.com/). Make sure
|
||||
that your question is tagged with the `pipenv` tag when asking it on
|
||||
Stack Overflow, to ensure that it is answered promptly and accurately.
|
||||
|
||||
## Good Bug Reports
|
||||
|
||||
Please be aware of the following things when filing bug reports:
|
||||
|
||||
1. Avoid raising duplicate issues. *Please* use the GitHub issue search feature
|
||||
to check whether your bug report or feature request has been mentioned in
|
||||
the past. Duplicate bug reports and feature requests are a huge maintenance
|
||||
burden on the limited resources of the project. If it is clear from your
|
||||
report that you would have struggled to find the original, that's ok, but
|
||||
if searching for a selection of words in your issue title would have found
|
||||
the duplicate then the issue will likely be closed extremely abruptly.
|
||||
2. When filing bug reports about exceptions or tracebacks, please include the
|
||||
*complete* traceback. Partial tracebacks, or just the exception text, are
|
||||
not helpful. Issues that do not contain complete tracebacks may be closed
|
||||
without warning.
|
||||
3. Make sure you provide a suitable amount of information to work with. This
|
||||
means you should provide:
|
||||
|
||||
- Guidance on **how to reproduce the issue**. Ideally, this should be a
|
||||
*small* code sample that can be run immediately by the maintainers.
|
||||
Failing that, let us know what you're doing, how often it happens, what
|
||||
environment you're using, etc. Be thorough: it prevents us needing to ask
|
||||
further questions.
|
||||
- Tell us **what you expected to happen**. When we run your example code,
|
||||
what are we expecting to happen? What does "success" look like for your
|
||||
code?
|
||||
- Tell us **what actually happens**. It's not helpful for you to say "it
|
||||
doesn't work" or "it fails". Tell us *how* it fails: do you get an
|
||||
exception? A hang? The packages installed seem incorrect?
|
||||
How was the actual result different from your expected result?
|
||||
- Tell us **what version of Pipenv you're using**, and
|
||||
**how you installed it**. Different versions of Pipenv behave
|
||||
differently and have different bugs, and some distributors of Pipenv
|
||||
ship patches on top of the code we supply.
|
||||
|
||||
If you do not provide all of these things, it will take us much longer to
|
||||
fix your problem. If we ask you to clarify these and you never respond, we
|
||||
will close your issue without fixing it.
|
||||
|
||||
## Development Setup
|
||||
|
||||
To get your development environment setup, run:
|
||||
|
||||
```sh
|
||||
pip install -e .
|
||||
pipenv install --dev
|
||||
```
|
||||
|
||||
This will install the repo version of Pipenv and then install the development
|
||||
dependencies. Once that has completed, you can start developing.
|
||||
|
||||
The repo version of Pipenv must be installed over other global versions to
|
||||
resolve conflicts with the `pipenv` folder being implicitly added to `sys.path`.
|
||||
See [pypa/pipenv#2557](https://github.com/pypa/pipenv/issues/2557) for more details.
|
||||
|
||||
### Testing
|
||||
|
||||
Tests are written in `pytest` style and can be run very simply:
|
||||
|
||||
```sh
|
||||
pytest
|
||||
```
|
||||
|
||||
This will run all Pipenv tests, which can take awhile. To run a subset of the
|
||||
tests, the standard pytest filters are available, such as:
|
||||
|
||||
- provide a directory or file: `pytest tests/unit` or `pytest tests/unit/test_cmdparse.py`
|
||||
- provide a keyword expression: `pytest -k test_lock_editable_vcs_without_install`
|
||||
- provide a nodeid: `pytest tests/unit/test_cmdparse.py::test_parse`
|
||||
- provide a test marker: `pytest -m lock`
|
||||
|
||||
#### Package Index
|
||||
|
||||
To speed up testing, tests that rely on a package index for locking and
|
||||
installing use a local server that contains vendored packages in the
|
||||
`tests/pypi` directory. Each vendored package should have it's own folder
|
||||
containing the necessary releases. When adding a release for a package, it is
|
||||
easiest to use either the `.tar.gz` or universal wheels (ex: `py2.py3-none`). If
|
||||
a `.tar.gz` or universal wheel is not available, add wheels for all available
|
||||
architectures and platforms.
|
||||
|
||||
+129
-14
@@ -20,8 +20,12 @@ 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.
|
||||
|
||||
|
||||
General Guidelines
|
||||
------------------
|
||||
|
||||
Be Cordial
|
||||
----------
|
||||
~~~~~~~~~~
|
||||
|
||||
**Be cordial or be on your way**. *—Kenneth Reitz*
|
||||
|
||||
@@ -34,10 +38,11 @@ everyone involved is treated with respect.
|
||||
|
||||
.. _be cordial or be on your way: https://www.kennethreitz.org/essays/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
|
||||
@@ -47,7 +52,7 @@ 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
|
||||
------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Our project maintainers have the last word on whether or not a contribution is
|
||||
suitable for Pipenv. All contributions will be considered carefully, but from
|
||||
@@ -58,22 +63,38 @@ If your contribution is rejected, don't despair! As long as you followed these
|
||||
guidelines, you will have a much better chance of getting your next
|
||||
contribution accepted.
|
||||
|
||||
|
||||
Questions
|
||||
---------
|
||||
|
||||
The GitHub issue tracker is for *bug reports* and *feature requests*. Please do
|
||||
not use it to ask questions about how to use Pipenv. These questions should
|
||||
instead be directed to `Stack Overflow`_. Make sure that your question is tagged
|
||||
with the ``pipenv`` tag when asking it on Stack Overflow, to ensure that it is
|
||||
answered promptly and accurately.
|
||||
|
||||
.. _Stack Overflow: https://stackoverflow.com/
|
||||
|
||||
|
||||
Code Contributions
|
||||
------------------
|
||||
|
||||
|
||||
Steps for Submitting Code
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When contributing code, you'll want to follow this checklist:
|
||||
|
||||
0. Understand our `development philosophy`_.
|
||||
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
|
||||
2. Set up your :ref:`dev-setup`
|
||||
3. Run the tests (:ref:`testing`) 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`.
|
||||
4. Write tests that demonstrate your bug or feature. Ensure that they fail.
|
||||
5. Make your change.
|
||||
6. 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
|
||||
@@ -81,6 +102,53 @@ When contributing code, you'll want to follow this checklist:
|
||||
|
||||
The following sub-sections go into more detail on some of the points above.
|
||||
|
||||
.. _development philosophy: https://docs.pipenv.org/dev/philosophy/
|
||||
|
||||
|
||||
.. _dev-setup:
|
||||
|
||||
Development Setup
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
To get your development environment setup, run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip install -e .
|
||||
pipenv install --dev
|
||||
|
||||
|
||||
This will install the repo version of Pipenv and then install the development
|
||||
dependencies. Once that has completed, you can start developing.
|
||||
|
||||
The repo version of Pipenv must be installed over other global versions to
|
||||
resolve conflicts with the ``pipenv`` folder being implicitly added to ``sys.path``.
|
||||
See `pypa/pipenv#2557`_ for more details.
|
||||
|
||||
.. _pypa/pipenv#2557: https://github.com/pypa/pipenv/issues/2557
|
||||
|
||||
|
||||
.. _testing:
|
||||
|
||||
Testing
|
||||
~~~~~~~
|
||||
|
||||
Tests are written in ``pytest`` style and can be run very simply:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pytest
|
||||
|
||||
|
||||
This will run all Pipenv tests, which can take awhile. To run a subset of the
|
||||
tests, the standard pytest filters are available, such as:
|
||||
|
||||
- provide a directory or file: ``pytest tests/unit`` or ``pytest tests/unit/test_cmdparse.py``
|
||||
- provide a keyword expression: ``pytest -k test_lock_editable_vcs_without_install``
|
||||
- provide a nodeid: ``pytest tests/unit/test_cmdparse.py::test_parse``
|
||||
- provide a test marker: ``pytest -m lock``
|
||||
|
||||
|
||||
Code Review
|
||||
~~~~~~~~~~~
|
||||
|
||||
@@ -90,6 +158,20 @@ 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.
|
||||
|
||||
|
||||
Package Index
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
To speed up testing, tests that rely on a package index for locking and
|
||||
installing use a local server that contains vendored packages in the
|
||||
``tests/pypi`` directory. Each vendored package should have it's own folder
|
||||
containing the necessary releases. When adding a release for a package, it is
|
||||
easiest to use either the ``.tar.gz`` or universal wheels (ex: ``py2.py3-none``). If
|
||||
a ``.tar.gz`` or universal wheel is not available, add wheels for all available
|
||||
architectures and platforms.
|
||||
|
||||
|
||||
|
||||
Documentation Contributions
|
||||
---------------------------
|
||||
|
||||
@@ -114,9 +196,42 @@ When presenting Python code, use single-quoted strings (``'hello'`` instead of
|
||||
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.
|
||||
Bug reports are hugely important! They are recorded as `GitHub issues`_. Please
|
||||
be aware of the following things when filing bug reports:
|
||||
|
||||
.. _GitHub issues: https://github.com/pypa/pipenv/issues
|
||||
|
||||
1. Avoid raising duplicate issues. *Please* use the GitHub issue search feature
|
||||
to check whether your bug report or feature request has been mentioned in
|
||||
the past. Duplicate bug reports and feature requests are a huge maintenance
|
||||
burden on the limited resources of the project. If it is clear from your
|
||||
report that you would have struggled to find the original, that's ok, but
|
||||
if searching for a selection of words in your issue title would have found
|
||||
the duplicate then the issue will likely be closed extremely abruptly.
|
||||
2. When filing bug reports about exceptions or tracebacks, please include the
|
||||
*complete* traceback. Partial tracebacks, or just the exception text, are
|
||||
not helpful. Issues that do not contain complete tracebacks may be closed
|
||||
without warning.
|
||||
3. Make sure you provide a suitable amount of information to work with. This
|
||||
means you should provide:
|
||||
|
||||
- Guidance on **how to reproduce the issue**. Ideally, this should be a
|
||||
*small* code sample that can be run immediately by the maintainers.
|
||||
Failing that, let us know what you're doing, how often it happens, what
|
||||
environment you're using, etc. Be thorough: it prevents us needing to ask
|
||||
further questions.
|
||||
- Tell us **what you expected to happen**. When we run your example code,
|
||||
what are we expecting to happen? What does "success" look like for your
|
||||
code?
|
||||
- Tell us **what actually happens**. It's not helpful for you to say "it
|
||||
doesn't work" or "it fails". Tell us *how* it fails: do you get an
|
||||
exception? A hang? The packages installed seem incorrect?
|
||||
How was the actual result different from your expected result?
|
||||
- Tell us **what version of Pipenv you're using**, and
|
||||
**how you installed it**. Different versions of Pipenv behave
|
||||
differently and have different bugs, and some distributors of Pipenv
|
||||
ship patches on top of the code we supply.
|
||||
|
||||
If you do not provide all of these things, it will take us much longer to
|
||||
fix your problem. If we ask you to clarify these and you never respond, we
|
||||
will close your issue without fixing it.
|
||||
|
||||
Reference in New Issue
Block a user