From f25368d18a05dba6bb96ff4d61928deb530354a3 Mon Sep 17 00:00:00 2001 From: LilSpazJoekp <15524072+LilSpazJoekp@users.noreply.github.com> Date: Sat, 4 Jun 2022 16:25:23 -0500 Subject: [PATCH] Improve contributing docs --- .github/CONTRIBUTING.rst | 42 +++++--- docs/package_info/contributing.rst | 155 +++++++++++++++++++++++------ 2 files changed, 148 insertions(+), 49 deletions(-) diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst index 6eaec6b7..287b5d7f 100644 --- a/.github/CONTRIBUTING.rst +++ b/.github/CONTRIBUTING.rst @@ -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 @@ -107,10 +114,11 @@ 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 @@ -118,6 +126,8 @@ https://asyncpraw.readthedocs.io/en/latest/package_info/contributing.html .. _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 diff --git a/docs/package_info/contributing.rst b/docs/package_info/contributing.rst index 7976089f..ea783cda 100644 --- a/docs/package_info/contributing.rst +++ b/docs/package_info/contributing.rst @@ -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 `_ 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 - pip install "asyncpraw[lint]" - pre-commit install + pre-commit install + +To run all the needed checks and to ensure the docs build correctly, run the following: + +.. code-block:: bash -Code ----- + ./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 @@ -42,23 +120,21 @@ 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 -`_. 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 ~~~~~~~~~~~~~~~~~~~~~~ -`GitHub Actions `_ automatically runs all -updates to known branches and pull requests. However, it's useful to be able to run the -tests locally. The simplest way is via: +`GitHub Actions`_ automatically runs all updates to known branches and pull requests. +However, it's useful to be able to run the tests locally. The simplest way is via: .. code-block:: bash @@ -70,8 +146,7 @@ please file a bug report. Adding and Updating Integration Tests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Async PRAW's integration tests utilize `vcrpy -`_ 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 @@ -108,8 +183,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 `_ - is its display name. + correct term for a subreddit's "name" like ``python`` for `r/python`_ is its display + name. Static Checker ~~~~~~~~~~~~~~ @@ -136,12 +211,26 @@ 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 -`_ 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 + +.. _github actions: https://github.com/praw-dev/asyncpraw/actions + +.. _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