diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c581b48e9..b3ff74ea6a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,34 +1,7 @@ -# Development +# Contributing -To start development you should begin by cloning the repo. +Thanks for the interest! See the [contributor documentation][contribute] +to get started, and reach out on [Gitter][gitter] if you get stuck. -```bash -$ git clone git@github.com/ethereum/web3.py.git -``` - - -# Cute Animal Pictures - -All pull requests need to have a cute animal picture. This is a very important -part of the development process. - - -# Pull Requests - -In general, pull requests are welcome. Please try to adhere to the following. - -- code should conform to PEP8 and as well as the linting done by `flake8 web3/ tests/` -- include tests. -- include any relevant documentation updates. - -It's a good idea to make pull requests early on. A pull request represents the -start of a discussion, and doesn't necessarily need to be the final, finished -submission. - -GitHub's documentation for working on pull requests is [available here](https://help.github.com/articles/about-pull-requests/). - -Always run the tests before submitting pull requests, and ideally run `tox` in -order to check that your modifications don't break anything. - -Once you've made a pull request take a look at the travis build status in the -GitHub interface and make sure the tests are runnning as you'd expect. +[contribute]: https://web3py.readthedocs.io/en/latest/contributing.html +[gitter]: https://gitter.im/ethereum/web3.py diff --git a/Makefile b/Makefile index 2c5a777651..94a0be5e2c 100644 --- a/Makefile +++ b/Makefile @@ -22,7 +22,7 @@ clean-pyc: find . -name '*~' -exec rm -f {} + lint: - tox -elint + tox -e lint lint-roll: isort --recursive web3 ens tests diff --git a/README.md b/README.md index 2a0b7dcc0d..47c5946d94 100644 --- a/README.md +++ b/README.md @@ -1,196 +1,25 @@ # Web3.py +[![Documentation Status](https://readthedocs.org/projects/web3py/badge/?version=latest)](https://web3py.readthedocs.io/en/latest/?badge=latest) [![Join the chat at https://gitter.im/ethereum/web3.py](https://badges.gitter.im/ethereum/web3.py.svg)](https://gitter.im/ethereum/web3.py?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - [![Build Status](https://circleci.com/gh/ethereum/web3.py.svg?style=shield)](https://circleci.com/gh/ethereum/web3.py) - -A Python implementation of [web3.js](https://github.com/ethereum/web3.js) +A Python library for interacting with Ethereum, inspired by [web3.js](https://github.com/ethereum/web3.js). * Python 3.6+ support -Read more in the [documentation on ReadTheDocs](http://web3py.readthedocs.io/). [View the change log on Github](docs/releases.rst). - -## Developer Setup - -```sh -git clone --recursive git@github.com:ethereum/web3.py.git -cd web3.py -``` - -Please see OS-specific instructions for: - -- [Linux](docs/README-linux.md#Developer-Setup) -- [Mac](docs/README-osx.md#Developer-Setup) -- [Windows](docs/README-windows.md#Developer-Setup) -- [FreeBSD](docs/README-freebsd.md#Developer-Setup) - -Then run these install commands: - -```sh -virtualenv venv -. venv/bin/activate -pip install -e .[dev] -``` - -For different environments, you can set up multiple `virtualenv`. For example, if you want to create a `venvdocs`, then you do the following: - -```sh -virtualenv venvdocs -. venvdocs/bin/activate -pip install -e .[docs] -pip install -e . -``` - -## Using Docker - -If you would like to develop and test inside a Docker environment, use the *sandbox* container provided in the **docker-compose.yml** file. - -To start up the test environment, run: - -``` -docker-compose up -d -``` - -This will build a Docker container set up with an environment to run the Python test code. - -**Note: This container does not have `go-ethereum` installed, so you cannot run the go-ethereum test suite.** - -To run the Python tests from your local machine: - -``` -docker-compose exec sandbox bash -c 'pytest -n 4 -f -k "not goethereum"' -``` - -You can run arbitrary commands inside the Docker container by using the `bash -c` prefix. - -``` -docker-compose exec sandbox bash -c '' -``` - -Or, if you would like to just open a session to the container, run: - -``` -docker-compose exec sandbox bash -``` - -### Testing Setup - -During development, you might like to have tests run on every file save. - -Show flake8 errors on file change: - -```sh -# Test flake8 -when-changed -v -s -r -1 web3/ tests/ ens/ -c "clear; flake8 web3 tests ens && echo 'flake8 success' || echo 'error'" -``` - -You can use `pytest-watch`, running one for every Python environment: - -```sh -pip install pytest-watch - -cd venv -ptw --onfail "notify-send -t 5000 'Test failure ⚠⚠⚠⚠⚠' 'python 3 test on web3.py failed'" ../tests ../web3 -``` - -Or, you can run multi-process tests in one command, but without color: - -```sh -# in the project root: -pytest --numprocesses=4 --looponfail --maxfail=1 -# the same thing, succinctly: -pytest -n 4 -f --maxfail=1 -``` - -#### How to Execute the Tests? - -1. [Setup your development environment](https://github.com/ethereum/web3.py/#developer-setup). - -2. Execute `tox` for the tests - -There are multiple [components](https://github.com/ethereum/web3.py/blob/master/.circleci/config.yml#L144) of the tests. You can run test to against specific component. For example: - -```sh -# Run Tests for the Core component (for Python 3.6): -tox -e py36-core - -# Run Tests for the Core component (for Python 3.7): -tox -e py37-core -``` - -If for some reason it is not working, add `--recreate` params. - -`tox` is good for testing against the full set of build targets. But if you want to run the tests individually, `pytest` is better for development workflow. For example, to run only the tests in one file: - -```sh -pytest tests/core/gas-strategies/test_time_based_gas_price_strategy.py -``` - -### Release setup - -For Debian-like systems: -``` -apt install pandoc -``` - -The final step before releasing is to build and test the code that will be released. -There is a test script that will build and install the wheel locally, -then generate a temporary virtualenv where you can do some smoke testing: - -``` -# Branch name could be either master or a version branch - ex. v5 - -$ git checkout && git pull - -$ make package - -# in another shell, navigate to the virtualenv mentioned in output of ^ - -# load the virtualenv with the packaged trinity release -$ source package-smoke-test/bin/activate - -# smoke test the release -$ pip install ipython -$ ipython ->>> from web3.auto import w3 ->>> w3.isConnected() ->>> ... -``` - -To preview the upcoming documentation: - -```sh -make docs -``` - -To preview the upcoming release notes: - -```sh -towncrier --draft -``` - -To compile and commit the release notes: - -```sh -make notes bump=$$VERSION_PART_TO_BUMP$$ -``` - -When the release notes are ready, release a new version: - -```sh -make release bump=$$VERSION_PART_TO_BUMP$$ -``` +## Quickstart -#### How to bumpversion +[Get started in 5 minutes](https://web3py.readthedocs.io/en/latest/quickstart.html) or +[take a tour](https://web3py.readthedocs.io/en/latest/overview.html) of the library. -The version format for this repo is `{major}.{minor}.{patch}` for stable, and -`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta). +## Documentation -To issue the next version in line, specify which part to bump, -like `make release bump=minor` or `make release bump=devnum`. +For additional guides, examples, and APIs, see the [documentation](https://web3py.readthedocs.io/en/latest/). -If you are in a beta version, `make release bump=stage` will switch to a stable. +## Want to help? -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"` +Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on our +guidelines for [contributing](https://web3py.readthedocs.io/en/latest/contributing.html), +then check out issues that are labeled +[Good First Issue](https://github.com/ethereum/web3.py/issues?q=is%3Aissue+is%3Aopen+label%3A%22Good+First+Issue%22). diff --git a/docs/code_of_conduct.rst b/docs/code_of_conduct.rst new file mode 100644 index 0000000000..7fd2102d20 --- /dev/null +++ b/docs/code_of_conduct.rst @@ -0,0 +1,78 @@ +Code of Conduct +--------------- + +Our Pledge +~~~~~~~~~~ + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, +religion, or sexual identity and orientation. + +Our Standards +~~~~~~~~~~~~~ + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +Our Responsibilities +~~~~~~~~~~~~~~~~~~~~ + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +Scope +~~~~~ + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +Enforcement +~~~~~~~~~~~ + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at piper@pipermerriam.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +Attribution +~~~~~~~~~~~ + +This Code of Conduct is adapted from the `Contributor Covenant `_, version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000000..e0d087b69e --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,261 @@ +.. _contributing: + +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 our +`Gitter channel `_. + +Setting the stage +~~~~~~~~~~~~~~~~~ + +First, you need to clone the repository. Web3.py depends on submodules, so you +need to clone the repo with the ``--recursive`` flag. Example: + +.. code:: sh + + $ git clone --recursive https://github.com/ethereum/web3.py.git + $ cd web3.py + + +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. + +To start up the test environment, run: + +.. code:: sh + + $ docker-compose up -d + + +This will build a Docker container set up with an environment to run the +Python test code. + +.. note:: + + This container does not have `go-ethereum` installed, so you cannot run + the go-ethereum test suite. + +To run the Python tests from your local machine: + +.. code:: sh + + $ docker-compose exec sandbox bash -c 'pytest -n 4 -f -k "not goethereum"' + + +You can run arbitrary commands inside the Docker container by using the +`bash -c` prefix. + +.. code:: sh + + $ docker-compose exec sandbox bash -c '' + + +Or, if you would like to open a session to the container, run: + +.. code:: sh + + $ docker-compose exec sandbox bash + + +Running the tests +~~~~~~~~~~~~~~~~~ + +A great way to explore the code base is to run the tests. + +You can run all tests with: + +.. code:: sh + + $ pytest + + +However, running the entire test suite takes a very long time and is generally impractical. +Typically, you'll just want to run a subset instead, like: + +.. code:: sh + + $ pytest tests/core/eth-module/test_accounts.py + + +You can use ``tox`` to run all the tests for a given version of Python: + +.. code:: sh + + $ tox -e py37-core + + +Linting is also performed by the CI. You can save yourself some time by checking for +linting errors locally: + +.. code:: sh + + $ make lint + + +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`_. + + +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 + + def __init__(self, wrapped_db: DatabaseAPI) -> None: + self.wrapped_db = wrapped_db + self.reset() + + +Documentation +~~~~~~~~~~~~~ + +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 +~~~~~~~~~~~~~ + +It's a good idea to make pull requests early on. A pull request represents the +start of a discussion, and doesn't necessarily need to be the final, finished +submission. + +See GitHub's documentation for `working on pull requests`_. + +Once you've made a pull request take a look at the Circle CI build status in +the GitHub interface and make sure all tests are passing. In general, pull +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 `_ + +If possible, the change to the release notes file should be included in the +commit that introduces the feature or bugfix. + + +Releasing +~~~~~~~~~ + +Final test before each release +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Before releasing a new version, build and test the package that will be released. +There's a script to build and install the wheel locally, then generate a temporary +virtualenv for smoke testing: + +.. code:: sh + + $ git checkout master && git pull + + $ make package + + # in another shell, navigate to the virtualenv mentioned in output of ^ + + # load the virtualenv with the packaged web3.py release + $ source package-smoke-test/bin/activate + + # smoke test the release + $ pip install ipython + $ ipython + >>> from web3.auto import w3 + >>> w3.isConnected() + >>> ... + + +Verify the latest documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To preview the documentation that will get published: + +.. code:: sh + + $ make docs + + +Preview the release notes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: sh + + $ towncrier --draft + + +Compile the release notes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +After confirming that the release package looks okay, compile the release notes: + +.. code:: sh + + $ make notes bump=$$VERSION_PART_TO_BUMP$$ + + +You may need to fix up any broken release note fragments before committing. Keep +running ``make build-docs`` until it passes, then commit and carry on. + + +Push the release to GitHub & PyPI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After committing the compiled release notes and pushing them to the master +branch, release a new version: + +.. code:: sh + + $ make release bump=$$VERSION_PART_TO_BUMP$$ + + +Which version part to bump +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The version format for this repo is ``{major}.{minor}.{patch}`` for +stable, and ``{major}.{minor}.{patch}-{stage}.{devnum}`` for unstable +(``stage`` can be alpha or beta). + +During a release, specify which part to bump, like +``make release bump=minor`` or ``make release bump=devnum``. + +If you are in an alpha version, ``make release bump=stage`` will bump to beta. +If you are in a beta version, ``make release bump=stage`` will bump to a stable +version. + +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"``. + + +.. _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 +.. _working on pull requests: https://help.github.com/articles/about-pull-requests/ diff --git a/docs/index.rst b/docs/index.rst index 01e6d920ff..cf4d8c0462 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,6 +21,7 @@ Your next steps depend on where you're standing: - Ready to code? → :ref:`quickstart` - Interested in a quick tour? → :ref:`overview` - Need help debugging? → `StackExchange`_ +- Like to give back? → :ref:`Contribute ` - Want to chat? → `Gitter`_ Table of Contents @@ -67,6 +68,13 @@ Table of Contents gas_price ens +.. toctree:: + :maxdepth: 1 + :caption: Community + + contributing + code_of_conduct + Indices and tables ------------------ diff --git a/newsfragments/1691.doc.rst b/newsfragments/1691.doc.rst new file mode 100644 index 0000000000..aaa7ccf035 --- /dev/null +++ b/newsfragments/1691.doc.rst @@ -0,0 +1 @@ +Add contribution guidelines and a code of conduct.