diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6881c45e754..680c059c233 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,18 +1,25 @@ -Contributing -============ - Instructions for contributors ----------------------------- +In order to make a clone of the `GitHub `_ repo: open the link and press the "Fork" button on the upper-right menu of the web page. -In order to make a clone of the GitHub_ repo: open the link and press the -"Fork" button on the upper-right menu of the web page. - -I hope everybody knows how to work with git and github nowadays :) +If you'd like to learn more about Git and GitHub, `check out GitHub's helpful introduction +`_. Workflow is pretty straightforward: - 1. Clone the GitHub_ repo using the ``--recurse-submodules`` argument + 0. Make sure you are reading the latest version of this document. + It can be found in the GitHub_ repo in the ``docs`` subdirectory. + + 1. Clone your forked GitHub_ repo with the ``--recurse-submodules`` flag as shown in the command below, + ensuring to replace the placeholder with your github username: + + .. code-block:: shell + + $ git clone \ + https://github.com//aiohttp.git \ + --recurse-submodules + 2. Setup your machine with the required development environment @@ -20,7 +27,7 @@ Workflow is pretty straightforward: 4. Make sure all tests passed - 5. Add a file into the ``CHANGES`` folder, named after the ticket or PR number + 5. Add a file into the ``CHANGES`` folder (see `Changelog update `_ for how). 6. Commit changes to your own aiohttp clone @@ -28,9 +35,22 @@ Workflow is pretty straightforward: 8. Optionally make backport Pull Request(s) for landing a bug fix into released aiohttp versions. -.. important:: +.. note:: + + The project uses *Squash-and-Merge* strategy for *GitHub Merge* button. + + Basically it means that there is **no need to rebase** a Pull Request against + *master* branch. Just ``git merge`` *master* into your working copy (a fork) if + needed. The Pull Request is automatically squashed into the single commit + once the PR is accepted. + +.. note:: + + GitHub issue and pull request threads are automatically locked when there has + not been any recent activity for one year. Please open a `new issue + `_ for related bugs. - Please open the "`contributing `_" - documentation page to get detailed information about all steps. + If you feel like there are important points in the locked discussions, + please include those excerpts into that new issue. -.. _GitHub: https://github.com/aio-libs/aiohttp +.. export-point-instructions-for-contributors diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt index 5d5f922e6fb..ed0186df875 100644 --- a/CONTRIBUTORS.txt +++ b/CONTRIBUTORS.txt @@ -329,6 +329,7 @@ Sunit Deshpande Sviatoslav Bulbakha Sviatoslav Sydorenko Taha Jahangir +Tambe Tabitha Achere Taras Voinarovskyi Terence Honles Thanos Lefteris diff --git a/docs/contributing.rst b/docs/contributing.rst index d35e9cd9c4f..d93d0d44622 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,61 +1,16 @@ .. _aiohttp-contributing: -Contributing -============ +.. include:: ../CONTRIBUTING.rst + :end-before: export-point-instructions-for-contributors (:doc:`contributing-admins`) -Instructions for contributors ------------------------------ - -In order to make a clone of the GitHub_ repo: open the link and press the "Fork" button on the upper-right menu of the web page. - -I hope everybody knows how to work with git and github nowadays :) - -Workflow is pretty straightforward: - - 0. Make sure you are reading the latest version of this document. - It can be found in the GitHub_ repo in the ``docs`` subdirectory. - - 1. Clone the GitHub_ repo using the ``--recurse-submodules`` argument - - 2. Setup your machine with the required development environment - - 3. Make a change - - 4. Make sure all tests passed - - 5. Add a file into the ``CHANGES`` folder (see `Changelog update`_ for how). - - 6. Commit changes to your own aiohttp clone - - 7. Make a pull request from the github page of your clone against the master branch - - 8. Optionally make backport Pull Request(s) for landing a bug fix into released aiohttp versions. - -.. note:: - - The project uses *Squash-and-Merge* strategy for *GitHub Merge* button. - - Basically it means that there is **no need to rebase** a Pull Request against - *master* branch. Just ``git merge`` *master* into your working copy (a fork) if - needed. The Pull Request is automatically squashed into the single commit - once the PR is accepted. - -.. note:: - - GitHub issue and pull request threads are automatically locked when there has - not been any recent activity for one year. Please open a `new issue - `_ for related bugs. - - If you feel like there are important points in the locked discussions, - please include those excerpts into that new issue. - - Preconditions for running aiohttp test suite -------------------------------------------- We expect you to use a python virtual environment to run our tests. +Also, ensure that you have `npm +`_ installed. There are several ways to make a virtual environment. @@ -237,10 +192,23 @@ Please before making a Pull Request about documentation changes run: $ make doc Once it finishes it will output the index html page + ``open file:///.../aiohttp/docs/_build/html/index.html``. Go to the link and make sure your doc changes looks good. +Note that this page doesn't automatically refresh itself. So, if you make more changes, build the docs again to see how they look on the page. + +.. note:: + If you are on MacOS, you might need to install `graphviz `_ first. + Use + + .. code-block:: shell + + $ brew install graphviz + + and then run the command above to build the docs. + Spell checking --------------