Skip to content

Latest commit

 

History

History
239 lines (159 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

239 lines (159 loc) · 10.7 KB
Raw

Contributing

Set up your dev environment

If you want to contribute code to xrpl-py, the following sections describe how to set up your developer environment.

Set up Python environment

To make it easy to manage your Python environment with xrpl-py, including switching between versions, install pyenv and follow these steps:

  • Install pyenv:

      brew install pyenv

    For other installation options, see the pyenv README.

  • Use pyenv to install the optimized version for xrpl-py (currently 3.11.6):

      pyenv install 3.11.6

  • Set the global version of Python with pyenv:

      pyenv global 3.11.6

Set up shell environment

To enable autocompletion and other functionality from your shell, add pyenv to your environment.

These steps assume that you're using a Zsh shell. For other shells, see the pyenv README.

  • Add pyenv init to your Zsh shell:

      echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\n  eval "$(pyenv init -)"\nfi' >> ~/.zshrc

  • Source or restart your terminal:

      . ~/.zshrc

Manage dependencies and virtual environments

To simplify managing library dependencies and the virtual environment, xrpl-py uses poetry.

  • Install poetry:

      curl -sSL https://install.python-poetry.org | python3 -

May need to run export PATH="$HOME/.local/bin:$PATH" to invoke Poetry (see step 3 "Add Poetry to your PATH").

Set up pre-commit hooks

To run linting and other checks, xrpl-py uses pre-commit.

Note: You only need to install pre-commit if you want to contribute code to xrpl-py.

  • Install pre-commit:

      pip3 install pre-commit
  pre-commit install

Run the linter

To run the linter:

poetry run flake8 xrpl tests --darglint-ignore-regex="^_(.*)"

Running Tests

Individual Tests

# Works for single or multiple unit/integration tests
# Ex: poetry run poe test tests/unit/models/test_response.py tests/integration/transactions/test_account_delete.py
poetry run poe test FILE_PATHS

Unit Tests

poetry run poe test_unit

Integration Tests

To run integration tests, you'll need a standalone rippled node running with WS port 6006 and JSON RPC port 5005. You can run a docker container for this:

docker run -p 5005:5005 -p 6006:6006 --interactive -t --volume $PWD/.ci-config:/opt/ripple/etc/ --platform linux/amd64 rippleci/rippled:2.2.0-b3 /opt/ripple/bin/rippled -a --conf /opt/ripple/etc/rippled.cfg

Breaking down the command:

  • docker run -p 5005:5005 -p 6006:6006 starts a Docker container with an open port for admin JsonRPC and WebSocket requests.
  • --interactive allows you to interact with the container.
  • -t starts a terminal in the container for you to send commands to.
  • --volume $PWD/.ci-config:/config/ identifies the rippled.cfg and validators.txt to import. It must be an absolute path, so we use $PWD instead of ./.
  • xrpllabsofficial/xrpld:1.12.0 is an image that is regularly updated with the latest rippled releases and can be found here: https://github.com/WietseWind/docker-rippled
  • -a starts rippled in standalone mode
  • --start signals to start rippled with the specified amendments in rippled.cfg enabled immediately instead of voting for 2 weeks on them.

Then to actually run the tests, run the command:

poetry run poe test_integration

Code Coverage

To run both unit and integration tests and see code coverage:

poetry run poe test_coverage

To see manually code coverage after running unit tests or integration tests:

poetry run coverage report

Running tests with different Python versions

To switch your python version before running tests:

pyenv local 3.11
poetry env use python3.11
poetry install

Replace python3.11 with whatever version of Python you want to use (you must have it installed with pyenv for it to work).

Generate reference docs

You can see the complete reference documentation at xrpl-py docs. You can also generate them locally using poetry and sphinx:

# Go to the docs/ folder
cd docs/

# Build the docs
poetry run sphinx-apidoc -o source/ ../xrpl
poetry run make html

To see the output:

# Go to docs/_build/html/
cd docs/_build/html/

# Open the index file to view it in a browser:
open index.html

You can view docs builds for xrpl-py versions on the ReadTheDocs website here: https://readthedocs.org/projects/xrpl-py/builds/

In order to test how a change in docs configuration looks like on ReadTheDocs before merging:

  1. Publish a branch with your docs configuration changes
  2. Active and hide the branch by scrolling down on this page: https://readthedocs.org/projects/xrpl-py/versions/
  3. View the page / build results here: https://readthedocs.org/projects/xrpl-py/builds/
  4. Once you're done testing, make the test branch inactive.

Write integration tests

  1. If adding functionality to a new part of the library, create new file with a class that inherits IntegrationTestCase from tests.integration.integration_test_case to store all individual tests under (ex: class TestWallet(IntegrationTestCase)). Otherwise, add to an existing file.
  2. Create an async function for each test case (unless the test is only being used for the sync client)
  3. Include the @test_async_and_sync decorator to test against all client types, unless you specifically only want to test with one client. You can also use the decorator to:
    • Limit tests to sync/async only
    • Limit the number of retries
    • Use Testnet instead of a standalone network
    • Import modules for sync equivalents of any async functions used
  4. Be sure to reuse pre-made values, WALLET, DESTINATION, TESTNET_WALLET, TESTNET_DESTINATION, OFFER, and PAYMENT_CHANNEL, from tests/integrations/reusable_values.py
  5. Be sure to use condensed functions, like submit_transaction_async and sign_and_reliable_submission_async, from tests/integrations/it_utils.py

Examples can be found in subfolders of tests/integrations

Updating definitions.json

This should almost always be done using the xrpl-codec-gen script - if the output needs manual intervention afterwards, consider updating the script instead.

  1. Clone / pull the latest changes from rippled - Specifically the develop branch is usually the right one.
  2. Clone / pull the latest changes from xrpl-codec-gen
  3. From the xrpl-codec-gen tool, follow the steps in the README.md to generate a new definitions.json file.
  4. Replace the definitions.json file in the ripple-binary-codec with the newly generated file.
  5. Verify that the changes make sense by inspection before submitting, as there may be updates required for the xrpl-codec-gen tool depending on the latest amendments we're updating to match.

Release process

Editing the Code

  • Your changes should have unit and/or integration tests.
  • Your changes should pass the linter.
  • Your code should pass all the unit and integration tests on Github (which check all versions of Python).
  • Open a PR against main and ensure that all CI passes.
  • Get a full code review from one of the maintainers.
  • Merge your changes.

Release

  1. Please increment the version in pyproject.toml and update the CHANGELOG.md file appropriately. We follow Semantic Versioning.
  2. Please select a commit that is suitable for release and create a tag. The following commands can be helpful: git tag -s -a <tag-title> -m "Optional Message describing the tag" git tag -- This command displays all the tags in the repository. git push <remote_name, e.g. upstream> tag <tag_title>
  3. A Github Workflow completes the rest of the Release steps (building the project, generating a .whl and tarball, publishing on the PyPI platform). The workflow uses OpenID Connect's temporary keys to obtain the necessary PyPI authorization. As a prerequisite, the PyPI xrpl-py project needs to authorize Github Actions as a "Trusted Publisher". This page contains helpful resources: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/#configuring-trusted-publishing
  4. Send an email to xrpl-announce.
  5. Post an announcement in the XRPL Discord #python channel with a link to the changes and highlighting key changes.

Note: If maintainers prefer to manually release the xrpl-py software distribution, the below steps are relevant.

  1. Create a branch off main that properly increments the version in pyproject.toml and updates the CHANGELOG appropriately. We follow Semantic Versioning.
  2. Merge this branch into main.
  3. Locally build and download the package.
    1. Pull main locally.
    2. Run poetry build to build the package locally.
    3. Locally download the package by running pip install path/to/local/xrpl-py/dist/.whl.
    4. Make sure that this local installation works as intended, and that the changes are reflected properly.
  4. Run poetry publish --dry-run and make sure everything looks good.
  5. Publish the update by running poetry publish.
    • This will require entering PyPI login info.
  6. Create a new Github release/tag off of this branch.
  7. Send an email to xrpl-announce.
  8. Post an announcement in the XRPL Discord #python channel with a link to the changes and highlighting key changes.

Mailing Lists

We have a low-traffic mailing list for announcements of new xrpl-py releases. (About 1 email every couple of weeks)

If you're using the XRP Ledger in production, you should run a rippled server and subscribe to the ripple-server mailing list as well.