diff --git a/Makefile b/Makefile index a8af4eba..5f731893 100644 --- a/Makefile +++ b/Makefile @@ -74,8 +74,8 @@ notes: check-bump git commit -m "Compile release notes" release: check-bump clean - # require that you be on a branch that's linked to upstream/master - git status -s -b | head -1 | grep "\.\.upstream/master" + # require that you be on a branch that's linked to upstream/main + git status -s -b | head -1 | grep "\.\.upstream/main" # verify that docs build correctly ./newsfragments/validate_files.py is-empty make build-docs diff --git a/README.md b/README.md index 86b1e410..7d126455 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@ [![PyPI version](https://badge.fury.io/py/.svg)](https://badge.fury.io/py/) [![Python versions](https://img.shields.io/pypi/pyversions/.svg)](https://pypi.python.org/pypi/) [![Docs build](https://readthedocs.org/projects//badge/?version=latest)](https://.readthedocs.io/en/latest/?badge=latest) - @@ -23,10 +22,10 @@ If you would like to hack on , please check out the [Snake Charmers Tactical Manual](https://github.com/ethereum/snake-charmers-tactical-manual) for information on how we do: -- Testing -- Pull Requests -- Code Style -- Documentation +- Testing +- Pull Requests +- Code Style +- Documentation ### Development Environment Setup @@ -55,7 +54,7 @@ The version format for this repo is `{major}.{minor}.{patch}` for stable, and To issue the next version in line, specify which part to bump, like `make release bump=minor` or `make release bump=devnum`. This is typically done from the -master branch, except when releasing a beta (in which case the beta is released from master, +main branch, except when releasing a beta (in which case the beta is released from main, and the previous stable branch is released from said branch). If you are in a beta version, `make release bump=stage` will switch to a stable. diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..926b87ce --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,161 @@ +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. + + +Setting the stage +~~~~~~~~~~~~~~~~~ + +First, we need to clone the repository: + +.. code:: sh + + $ git clone https://github.com/ethereum/.git + + +.. include:: /fragments/virtualenv_explainer.rst + +After we have activated our virtual environment, we need to install all dependencies that are needed to run, develop, and test. +This is as easy as navigating to the directory and running: + +.. code:: sh + + pip install -e ".[dev]" + + +Running the tests +~~~~~~~~~~~~~~~~~ + +A great way to explore the code base is to run the tests. + +We can run all tests with: + +.. code:: sh + + pytest tests + +However, you may just want to run a subset instead, like: + +.. code:: sh + + pytest tests/core/padding-utils/test_padding.py + + +We can also install ``tox`` to run the full test suite which also covers things like testing the code against different Python versions, linting etc. + +It is important to understand that each Pull Request must pass the full test suite as part of the CI check, hence it is often convenient to have ``tox`` installed locally as well. + + +Code Style +~~~~~~~~~~ + +When multiple people are working on the same body of code, it is important that they write code that conforms to a similar style. It often doesn't matter as much which style, but rather that they conform to one style. + +To ensure your contribution conforms to the style being used in this project, we encourage you to read our `style guide `_. + + +Type Hints +~~~~~~~~~~ + +This codebase uses `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 land with type hints, with the exception of test code that is not expected to use type hints. + +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. + +GitHub's documentation for working on pull requests is `available here `_. + +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 /blob/main/newsfragments/README.md>`_. + +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: + +.. code:: sh + + git checkout main && git pull + + make package + + + # Preview the upcoming release notes + towncrier --draft + + +Build the release notes +^^^^^^^^^^^^^^^^^^^^^^^ + +Before bumping the version number, build the release notes. +You must include the part of the version to bump (see below), +which changes how the version number will show in the release notes. + +.. code:: sh + + make notes bump=$$VERSION_PART_TO_BUMP$$ + +If there are any errors, be sure to re-run ``make notes`` until it works. + + +Push the release to github & pypi +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After confirming that the release package looks okay, 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 a beta version, ``make release bump=stage`` will switch to a +stable. + +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"`` diff --git a/docs/fragments/virtualenv_explainer.rst b/docs/fragments/virtualenv_explainer.rst new file mode 100644 index 00000000..ecc6d4c6 --- /dev/null +++ b/docs/fragments/virtualenv_explainer.rst @@ -0,0 +1,25 @@ +**Optional:** Often, the best way to guarantee a clean Python 3 environment is with +`virtualenv `_. If we don't have ``virtualenv`` installed +already, we first need to install it via pip. + +.. code:: sh + + pip install virtualenv + +Then, we can initialize a new virtual environment ``venv``, like: + +.. code:: sh + + virtualenv -p python3 venv + +This creates a new directory ``venv`` where packages are installed isolated from any other global +packages. + +To activate the virtual directory we have to *source* it + +.. code:: sh + + . venv/bin/activate + + # and when leaving this context: + deactivate diff --git a/docs/index.rst b/docs/index.rst index 89815efa..4f1f0b31 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,12 @@ Contents release_notes + +.. toctree:: + :maxdepth: 1 + :caption: Community + + contributing Indices and tables diff --git a/pyproject.toml b/pyproject.toml index 64f8b8af..aa7ddcd0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [tool.towncrier] -# Read https://github.com/ethereum//blob/master/newsfragments/README.md for instructions +# Read https://github.com/ethereum//blob/main/newsfragments/README.md for instructions package = "" filename = "docs/release_notes.rst" directory = "newsfragments"