Skip to content

Commit

Permalink
Improve contributing docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@LilSpazJoekp
LilSpazJoekp committed Jun 11, 2022
1 parent e930b5c commit f264518
Show file tree
Hide file tree
Showing 2 changed files with 144 additions and 46 deletions.
42 changes: 26 additions & 16 deletions .github/CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,26 +29,33 @@ Creating Pull Requests

1. If you are fixing an already filed issue, please indicate your intentions by
commenting on the issue. This act will hopefully minimize any duplicate work.
2. Before committing, make sure to install pre-commit_ and the pre-commit hooks, which
2. You will need to clone the repository and open the project in the IDE of your choice.
Note: the following commands need to executed within the project directory.
3. Install the development dependencies with ``pip install -e ".[dev]"``. This will
install Async PRAW in an editable state which will make development, testing, and
debugging easier. This will also install all the needed dependencies for linting and
testing. `See here`_ for more information on installing the development dependencies.
4. Before committing, make sure to install pre-commit_ and the pre-commit hooks, which
ensures any new code conforms to our quality and style guidelines. To do so, install
the linting dependencies with ``pip install asyncpraw[lint]``, then by the hooks with
``pre-commit install``. They will now run automatically every time you commit. If one
of the hooks changes one or more files, the commit will automatically abort, so you
can double-check the changes. If everything looks good try committing again.
3. Prior to creating a pull request, run the ``pre_push.py`` script. This runs the
the development dependencies mentioned previously or just the linting dependencies
with ``pip install ".[lint]"``, then install the hooks with ``pre-commit install``.
They will now run automatically every time you commit. If one of the hooks changes
one or more files, the commit will automatically abort, so you can double-check the
changes. If everything looks good try committing again.
5. Prior to creating a pull request, run the ``pre_push.py`` script. This runs the
pre-commit suite on all files, as well as builds the docs. You'll need to have
installed the linting dependencies first (see previous).
4. Add yourself as a contributor to appropriate section in the ``AUTHORS.rst`` file.
5. Once pushed, ensure that your GitHub Actions build succeeds. If this is your first
time contributing to the repository, you will need to wait for a team member to allow
installed the linting dependencies first (see previous step).
6. Add yourself as a contributor to appropriate section in the ``AUTHORS.rst`` file.
7. Once pushed, ensure that your GitHub Actions build succeeds. If this is your first
time contributing to the repository, you may need to wait for a team member to allow
GitHub Actions to run. GitHub Actions will error if there are *any* linting or test
failures. Resolve any issues by updating your pull request.
6. Ensure that your code change has complete test coverage. Tests on methods that do not
8. Ensure that your code change has complete test coverage. Tests on methods that do not
require fetching data from Reddit, e.g., method argument validation, should be saved
as a unit test. Tests that hit Reddit's servers will be an integration test and all
network activity will be recorded via vcrpy. The required packages can be installed
with ``pip install asyncpraw[test]``.
7. Feel free to check on the status of your pull request periodically by adding a
with ``pip install ".[test]"``.
9. Feel free to check on the status of your pull request periodically by adding a
comment.

Becoming a Team Member
Expand Down Expand Up @@ -107,17 +114,20 @@ Method Order within a Class
pass
See Also
~~~~~~~~
--------

Please also read through:
https://asyncpraw.readthedocs.io/en/latest/package_info/contributing.html
Please also read `Contributing to Async PRAW`_.

.. _contributing to async praw: https://asyncpraw.readthedocs.io/en/latest/package_info/contributing.html

.. _contributor code of conduct: https://github.com/praw-dev/.github/blob/main/CODE_OF_CONDUCT.md

.. _pre-commit: https://pre-commit.com

.. _r/redditdev: https://redditdev.reddit.com

.. _see here: https://asyncpraw.readthedocs.io/en/latest/package_info/contributing.html#install-development-dependencies

.. _slack: https://join.slack.com/t/praw/shared_invite/enQtOTUwMDcxOTQ0NzY5LWVkMGQ3ZDk5YmQ5MDEwYTZmMmJkMTJkNjBkNTY3OTU0Y2E2NGRlY2ZhZTAzMWZmMWRiMTMwYjdjODkxOGYyZjY

.. _unreleased: https://github.com/praw-dev/asyncpraw/blob/master/CHANGES.rst#unreleased
148 changes: 118 additions & 30 deletions docs/package_info/contributing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,32 +5,110 @@ Async PRAW gladly welcomes new contributions. As with most larger projects, we h
established consistent way of doing things. A consistent style increases readability,
decreases bug-potential and makes it faster to understand how everything works together.

Async PRAW follows :PEP:`8` and :PEP:`257`. `pre-commit <https://pre-commit.com>`_ is
used to manage a suite of pre-commit hooks that enforce conformance with these PEPs
along with several other checks. Additionally, the ``pre_push.py`` script can be used to
run the full pre-commit suite and the docs build prior to submitting a pull request. The
following are Async PRAW-specific guidelines in addition to those PEPs.
Setting Up Your Development Environment
---------------------------------------

This section will cover the recommended steps to get you started with contributing to
Async PRAW.

Create a Virtual Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is strongly recommended to use a virtual environment to isolate your development
environment. This is a good idea because it will make managing the needed dependencies
and their versions much easier. For more information, see the `venv documentation`_.
Assuming you have the minimum Python version required for Async PRAW, you can create a
virtual environment with the following commands from the root of the cloned project
directory:

.. code-block:: bash
python3 -m venv .venv
Next you need to activate the virtual environment. This is done by running the
following:

**MacOS/Linux**:

.. code-block:: bash
source .venv/bin/activate
**Windows Command Prompt**

.. code-block:: bat
.venv\Scripts\activate.bat
.. _install_dev_deps:

Install Development Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Next, you will need to install the dependencies development dependencies. This is done
by running the following:

.. code-block:: bash
pip install -e .[dev]
.. important::

If you are using ``zsh`` for your shell, you will need to double-quote ``.[dev]``
like so:

.. code-block:: zsh
pip install -e ".[dev]"
.. note::

The ``-e`` tells pip to install Async PRAW in an editable state. This will allow for
easier testing and debugging. The ``[dev]`` extra will install all development
dependencies. This includes the dependencies for both linting and testing.

Code Style
----------

Linting
~~~~~~~

Async PRAW follows :PEP:`8` and :PEP:`257` and some
:ref:`asyncpraw_specific_guidelines`. pre-commit_ is used to manage a suite of
pre-commit hooks that enforce conformance with these PEPs along with several other
checks. Additionally, the ``pre_push.py`` script can be used to run the full pre-commit
suite and the docs build prior to submitting a pull request.

.. note::

In order to use the pre-commit hooks and the ``pre_push.py`` dependencies, install
Async PRAW's ``[lint]`` extra, followed by the appropriate pre-commit command:
In order to use the pre-commit hooks and the ``pre_push.py`` dependencies, you must
either install the development dependencies as outlined in the
:ref:`install_dev_deps` section above or you must install the ``[lint]`` extra
manually:

.. code-block:: bash
pip install asyncpraw[lint]
pre-commit install
pip install -e .[lint]
If you are using ``zsh`` for your shell, you will need to double-quote
``"asyncpraw[lint]"`` like so:
To install the pre-commit hooks to automatically run when you commit, run the following:

.. code-block:: zsh
.. code-block:: bash
pre-commit install
pip install "asyncpraw[lint]"
pre-commit install
To run all the needed checks and to ensure the docs build correctly, run the following:

Code
----
.. code-block:: bash
./pre_push.py
.. _asyncpraw_specific_guidelines:

Async PRAW Specific Style Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following are Async PRAW-specific guidelines in addition to the PEPs specified in
Linting_:

- Within a single file classes are sorted alphabetically where inheritance permits.
- Within a class, methods are sorted alphabetically within their respective groups with
Expand All @@ -42,16 +120,15 @@ Code
- Properties
- Instance Methods

- Use descriptive names for the catch-all keyword argument. E.g., ``**other_options``
- Use descriptive names for the catch-all keyword argument. e.g., ``**other_options``
rather than ``**kwargs``.

Testing
-------

Contributions to Async PRAW requires 100% test coverage as reported by `Coveralls
<https://coveralls.io/github/praw-dev/asyncpraw>`_. If you know how to add a feature,
but aren't sure how to write the necessary tests, please open a pull request anyway so
we can work with you to write the necessary tests.
Contributions to Async PRAW requires 100% test coverage as reported by Coveralls_. If
you know how to add a feature, but aren't sure how to write the necessary tests, please
open a pull request anyway so we can work with you to write the necessary tests.

Running the Test Suite
~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -70,8 +147,7 @@ please file a bug report.
Adding and Updating Integration Tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Async PRAW's integration tests utilize `vcrpy
<https://vcrpy.readthedocs.io/en/latest/>`_ to record an interaction with Reddit. The
Async PRAW's integration tests utilize vcrpy_ to record an interaction with Reddit. The
recorded interaction is then replayed for subsequent test runs.

To safely record a cassette without leaking your account credentials, Async PRAW
Expand Down Expand Up @@ -108,8 +184,8 @@ Documentation
- All documentation files and docstrings should be linted and formatted by
``docstrfmt``.
- Use correct terminology. A subreddit's fullname is something like ``t5_xyfc7``. The
correct term for a subreddit's "name" like `python <https://www.reddit.com/r/python>`_
is its display name.
correct term for a subreddit's "name" like ``python`` for `r/python`_ is its display
name.

Static Checker
~~~~~~~~~~~~~~
Expand All @@ -136,12 +212,24 @@ CHANGES.rst

For feature additions, bugfixes, or code removal please add an appropriate entry to
``CHANGES.rst``. If the ``Unreleased`` section does not exist at the top of
``CHANGES.rst`` please add it. See `commit 280525c16ba28cdd69cdbb272a0e2764b1c7e6a0
<https://github.com/praw-dev/praw/commit/280525c16ba28cdd69cdbb272a0e2764b1c7e6a0>`_ for
an example.
``CHANGES.rst`` please add it. See `commit 280525c16ba28cdd69cdbb272a0e2764b1c7e6a0`_
for an example.

See Also
--------

Please also read through:
https://github.com/praw-dev/asyncpraw/blob/master/.github/CONTRIBUTING.rst
Please also read the `Contributing Guidelines`_

.. _commit 280525c16ba28cdd69cdbb272a0e2764b1c7e6a0: https://github.com/praw-dev/praw/commit/280525c16ba28cdd69cdbb272a0e2764b1c7e6a0

.. _contributing guidelines: https://github.com/praw-dev/asyncpraw/blob/master/.github/CONTRIBUTING.rst

.. _coveralls: https://coveralls.io/github/praw-dev/asyncpraw

.. _pre-commit: https://pre-commit.com

.. _r/python: https://www.reddit.com/r/python

.. _vcrpy: https://vcrpy.readthedocs.io/en/latest

.. _venv documentation: https://docs.python.org/3/library/venv.html

0 comments on commit f264518

Please sign in to comment.