Skip to content

reorder and add context to contributing docs #2008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 2, 2021
Merged

reorder and add context to contributing docs #2008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 145 additions & 107 deletions docs/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,40 +3,62 @@
Contributing
------------

Thank you for your interest in contributing! We welcome all contributions
no matter their size. Please read along to learn how to get started. If you
get stuck, feel free to reach for help in the
`Ethereum Python Discord server <https://discord.gg/GHryRvPB84>`_.
Thanks for your interest in contributing to Web3.py! Read on to learn what
would be helpful and how to go about it. If you get stuck along the way, reach
for help in the `Python Discord server`_.


Bug Reports
How to Help
~~~~~~~~~~~

If you think you've spotted a bug, `open an issue <https://github.com/ethereum/web3.py/issues/new>`_
on GitHub with as much detail as possible, preferably with code to reproduce the issue.
Without code:

* Answer user questions within GitHub issues, Stack Overflow, or the `Python Discord server`_.
* Write or record tutorial content.
* Improve our documentation (including typo fixes).
* `Open an issue <https://github.com/ethereum/web3.py/issues/new>`_ on GitHub to document a bug. Include as much detail as possible, e.g., how to reproduce the issue and any exception messages.

Setting the stage
~~~~~~~~~~~~~~~~~
With code:

* Fix a bug that has been reported in an issue.
* Add a feature that has been documented in an issue.
* Add a missing test case.

.. warning::

**Before you start:** always ask if a change would be desirable or let us know that
you plan to work on something! We don't want to waste your time on changes we can't
accept or duplicated effort.

First, you need to clone the repository. Web3.py depends on submodules, so you
need to clone the repo with the ``--recursive`` flag. Example:

Your Development Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::

Use of a virtual environment is strongly advised for minimizing dependency issues. See
`this article <https://realpython.com/effective-python-environment/#virtual-environments>`_
for usage patterns.

All pull requests are made from a fork of the repository; use the GitHub UI to create a fork.
Web3.py depends on `submodules <https://gist.github.com/gitaarik/8735255>`_, so when you clone
your fork to your local machine, include the ``--recursive`` flag:

.. code:: sh

$ git clone --recursive https://github.com/ethereum/web3.py.git
$ git clone --recursive https://github.com/<your-github-username>/web3.py.git
$ cd web3.py


Install all development dependencies:
Finally, install all development dependencies:

.. code:: sh

$ pip install -e ".[dev]"


Using Docker
~~~~~~~~~~~~
^^^^^^^^^^^^

Developing within Docker is not required, but if you prefer that workflow, use
the *sandbox* container provided in the **docker-compose.yml** file.
Expand Down Expand Up @@ -78,6 +100,32 @@ Or, if you would like to open a session to the container, run:
$ docker-compose exec sandbox bash


Code Style
~~~~~~~~~~

We value code consistency. To ensure your contribution conforms to the style
being used in this project, we encourage you to read our `style guide`_.


Type Hints
~~~~~~~~~~

This code base makes use of `type hints`_. Type hints make it easy to prevent
certain types of bugs, enable richer tooling, and enhance the documentation,
making the code easier to follow.

All new code is required to include type hints, with the exception of tests.

All parameters, as well as the return type of functions, are expected to be typed,
with the exception of ``self`` and ``cls`` as seen in the following example.

.. code:: python

def __init__(self, wrapped_db: DatabaseAPI) -> None:
self.wrapped_db = wrapped_db
self.reset()


Running the tests
~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -117,30 +165,16 @@ It is important to understand that each pull request must pass the full test
suite as part of the CI check. This test suite will run in the CI anytime a
pull request is opened or updated.

Code Style
~~~~~~~~~~

We value code consistency. To ensure your contribution conforms to the style
being used in this project, we encourage you to read our `style guide`_.
Manual Testing
~~~~~~~~~~~~~~

To import and test an unreleased version of Web3.py in another context,
you can install it from your development directory:

Type Hints
~~~~~~~~~~

This code base makes use of `type hints`_. Type hints make it easy to prevent
certain types of bugs, enable richer tooling, and enhance the documentation,
making the code easier to follow.

All new code is required to include type hints, with the exception of tests.

All parameters, as well as the return type of defs, are expected to be typed,
with the exception of ``self`` and ``cls`` as seen in the following example.

.. code:: python
.. code:: sh

def __init__(self, wrapped_db: DatabaseAPI) -> None:
self.wrapped_db = wrapped_db
self.reset()
$ pip install -e ../path/to/web3py


Documentation
Expand All @@ -150,6 +184,9 @@ Good documentation will lead to quicker adoption and happier users. Please
check out our guide on `how to create documentation`_ for the Python Ethereum
ecosystem.

Pull requests generate their own preview of the latest documentation at
``https://web3py--<pr-number>.org.readthedocs.build/en/<pr-number>/``.


Pull Requests
~~~~~~~~~~~~~
Expand All @@ -166,13 +203,84 @@ requests that do not pass the CI build yet won't get reviewed unless explicitly
requested.

If the pull request introduces changes that should be reflected in the release
notes, please add a `newsfragment` file as explained
`here <https://github.com/ethereum/web3.py/blob/master/newsfragments/README.md>`_
notes, please add a **newsfragment** file as explained
`here <https://github.com/ethereum/web3.py/blob/master/newsfragments/README.md>`_.

If possible, the change to the release notes file should be included in the
commit that introduces the feature or bugfix.


Generating new fixtures
~~~~~~~~~~~~~~~~~~~~~~~

Our integration tests make use of Geth and Parity/OpenEthereum private networks.
When new versions of the client software are introduced, new fixtures should be
generated.

.. note::

A "fixture" is a pre-synced network. It's the result of configuring and running
a client, deploying the test contracts, and saving the resulting state for
testing Web3.py functionality against.


Geth fixtures
^^^^^^^^^^^^^

1. Install the desired Geth version on your machine locally. We recommend `py-geth`_ for
this purpose, because it enables you to easily manage multiple versions of Geth.

Note that ``py-geth`` will need updating to support each new Geth version as well.
Add newer Geth version to py-geth is straightforward; see past commits for a template.

If py-geth has the Geth version you need, install that version locally. For example:

.. code:: sh

$ python -m geth.install v1.10.1

2. Specify the Geth binary and run the fixture creation script (from within the web3.py directory):

.. code:: sh

$ GETH_BINARY=~/.py-geth/geth-v1.10.1/bin/geth python ./tests/integration/generate_fixtures/go_ethereum.py ./tests/integration/geth-1.10.1-fixture

3. The output of this script is your fixture, a zip file, which is now stored in ``/tests/integration/``.
Update the ``/tests/integration/go_ethereum/conftest.py`` file to point to this new fixture. Delete the old fixture.

4. Run the tests. To ensure that the tests run with the correct Geth version locally,
you may again include the ``GETH_BINARY`` environment variable.


Parity/OpenEthereum fixtures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. The most reliable way to get a specific Parity/OE binary is to download
the source code via `GitHub releases`_.

2. `Build the binary`_ from source. (This is will take a few minutes.)

3. Specify the path to this binary in the ``get_parity_binary`` function
of the ``/tests/integration/generate_fixtures/parity.py`` file.

4. Run the fixture generation script:

.. code:: sh

$ python /tests/integration/generate_fixtures/parity.py /tests/integration/parity-X.Y.Z-fixture

5. The output of this script is your fixture, a zip file. Store the fixture in the
``/tests/integration/`` directory and update the ``/tests/integration/parity/conftest.py``
file to point the new fixture.

6. By this point, you may have noticed that Parity fixture generation relies
on a Geth network to sync from. In the output of the generation script are
the hashes of the various contracts that it mined. Update the corresponding
values in the ``/parity/conftest.py`` file with those hashes.

7. Run the tests.


Releasing
~~~~~~~~~

Expand Down Expand Up @@ -263,77 +371,7 @@ To issue an unstable version when the current version is stable, specify the new
version explicitly, like ``make release bump="--new-version 4.0.0-alpha.1 devnum"``.


Generating new fixtures
~~~~~~~~~~~~~~~~~~~~~~~

Our integration tests make use of Geth and Parity/OpenEthereum private networks.
When new versions of the client software are introduced, new fixtures should be
generated.

.. note::

A "fixture" is a pre-synced network. It's the result of configuring and running
a client, deploying the test contracts, and saving the resulting state for
testing Web3.py functionality against.


Geth fixtures
^^^^^^^^^^^^^

1. Install the desired Geth version on your machine locally. We recommend `py-geth`_ for
this purpose, because it enables you to easily manage multiple versions of Geth.

Note that ``py-geth`` will need updating to support each new Geth version as well.
Add newer Geth version to py-geth is straightforward; see past commits for a template.

If py-geth has the Geth version you need, install that version locally. For example:

.. code:: sh

$ python -m geth.install v1.10.1

2. Specify the Geth binary and run the fixture creation script (from within the web3.py directory):

.. code:: sh

$ GETH_BINARY=~/.py-geth/geth-v1.10.1/bin/geth python ./tests/integration/generate_fixtures/go_ethereum.py ./tests/integration/geth-1.10.1-fixture

3. The output of this script is your fixture, a zip file, which is now stored in ``/tests/integration/``.
Update the ``/tests/integration/go_ethereum/conftest.py`` file to point to this new fixture. Delete the old fixture.

4. Run the tests. To ensure that the tests run with the correct Geth version locally,
you may again include the ``GETH_BINARY`` environment variable.


Parity/OpenEthereum fixtures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. The most reliable way to get a specific Parity/OE binary is to download
the source code via `GitHub releases`_.

2. `Build the binary`_ from source. (This is will take a few minutes.)

3. Specify the path to this binary in the ``get_parity_binary`` function
of the ``/tests/integration/generate_fixtures/parity.py`` file.

4. Run the fixture generation script:

.. code:: sh

$ python /tests/integration/generate_fixtures/parity.py /tests/integration/parity-X.Y.Z-fixture

5. The output of this script is your fixture, a zip file. Store the fixture in the
``/tests/integration/`` directory and update the ``/tests/integration/parity/conftest.py``
file to point the new fixture.

6. By this point, you may have noticed that Parity fixture generation relies
on a Geth network to sync from. In the output of the generation script are
the hashes of the various contracts that it mined. Update the corresponding
values in the ``/parity/conftest.py`` file with those hashes.

7. Run the tests.


.. _Python Discord server: https://discord.gg/GHryRvPB84
.. _style guide: https://github.com/pipermerriam/ethereum-dev-tactical-manual/blob/master/style-guide.md
.. _type hints: https://www.python.org/dev/peps/pep-0484/
.. _how to create documentation: https://github.com/ethereum/snake-charmers-tactical-manual/blob/master/documentation.md
Expand Down
1 change: 1 addition & 0 deletions newsfragments/2008.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improve contributor documentation context and ordering.