diff --git a/DEVELOPING.md b/DEVELOPING.md index 0919269c..833974c9 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -3,24 +3,18 @@ - [Getting the Source](#get) - [Setting up a New Development Environment](#setup) - [Development](#dev) - - [General code quality checks](#general) - - [Updating documentation](#docs) - - [Updating API documentation](#api) - - [Updating dependencies](#deps) - - [Tests](#tests) - - [Miscellaneous checks](#misc) -- [Generating python types from Cosmos SDK protobuf schemas](#protobuf) -- [Setting up a local Fetchai node](#localnode) -- [Running a local Fetchai node in docker](#dockernode) +- [Testing](#test) - [Contributing](#contributing) ## Getting the Source -1. Fork the [repository][repo]. + +1. Fork the [repository](https://github.com/fetchai/cosmpy.git). 2. Clone your fork of the repository: + ``` shell - git clone git@github.com:/cosmpy.git + git clone https://github.com/fetchai/cosmpy.git ``` 3. Define an `upstream` remote pointing back to the main CosmPy repository: @@ -31,224 +25,38 @@ ## Setting up a New Development Environment -1. Ensure you have Python (version `3.8`, `3.9` or `3.10`) and [`poetry`][poetry]. +The easiest way to get set up for development is to install Python (`3.9` to `3.12`) and [poetry](https://pypi.org/project/poetry/), and then run the following from the top-level project directory: -2. ``` shell - make new-env - ``` - - This will create a new virtual environment using poetry with the project and all the development dependencies installed. - - > We use poetry to manage dependencies. All python specific dependencies are specified in `pyproject.toml` and installed with the library. - > - > You can have more control on the installed dependencies by leveraging poetry's features. - -3. ``` shell - poetry shell - ``` - - To enter the virtual environment. - -To [update the protobuf schemas](#protobuf) and generate their associated python types, you will need [Google Protocol Buffers][protobuf]. +```bash + cd python + poetry install + poetry shell + pre-commit install +``` ## Development -### General code quality checks - -To run general code quality checkers, formatters and linters: - -- ``` shell - make lint - ``` - - Automatically formats your code and sorts your imports, checks your code's quality and scans for any unused code. - -- ``` shell - make mypy - ``` - - Statically checks the correctness of the types. - -- ``` shell - make pylint - ``` - - Analyses the quality of your code. - -- ``` shell - make security - ``` - - Checks the code for known vulnerabilities and common security issues. - -- ``` shell - make clean - ``` - - Cleans your development environment and deletes temporary files and directories. - -### Updating documentation - -We use [`mkdocs`][mkdocs] and [`material-for-mkdocs`][material] for static documentation pages. To make changes to the documentation: - -- ``` shell - make docs-live - ``` - - This starts a live-reloading docs server on localhost which you can access by going to in your browser. Making changes to the documentation automatically reloads this page, showing you the latest changes. - - To create a new documentation page, add a markdown file under `/docs/` and add a reference to this page in `mkdocs.yml` under `nav`. - -### Updating API documentation - -If you've made changes to the core `cosmpy` package that affects the public API: - -- ``` shell - make generate-api-docs - ``` - - This regenerates the API docs. If pages are added/deleted, or there are changes in their structure, these need to be reflected manually in the `nav` section of `mkdocs.yaml`. - -### Updating dependencies - -We use [`poetry`][poetry] and `pyproject.toml` to manage the project's dependencies. - -If you've made any changes to the dependencies (e.g. added/removed dependencies, or updated package version requirements): - -- ``` shell - poetry lock - ``` - - This re-locks the dependencies. Ensure that the `poetry.lock` file is pushed into the repository (by default it is). - -- ``` shell - make liccheck - ``` - - Checks that the licence for the library is correct, taking into account the licences for all dependencies, their dependencies and so forth. - -### Tests - -To test the project, we use `pytest`. To run the tests: - -- ``` shell - make test - ``` - - Runs all the tests. - -- ``` shell - make unit-test - ``` - - Runs all unit tests. - -- ``` shell - make integration-test - ``` - - Runs all integration tests. - -- ``` shell - make coverage-report - ``` - - Produces a coverage report (you should run tests using one of the above commands first). - -### Miscellaneous checks - -- ``` shell - make copyright-check - ``` - - Checks that all files have the correct copyright header (where applicable). - -## Generating python types from Cosmos SDK protobuf schemas - -This library uses python types which are generated (using [Google's Protocol Buffers](https://developers.google.com/protocol-buffers/) compiler) from protocol buffer schemas in the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) and [WasmD](https://github.com/CosmWasm/wasmd). - -When updating the Cosmos-SDK version that is supported by this library (see the version currently used under `COSMOS_SDK_VERSION` in [Makefile](Makefile)), you will need to fetch its corresponding protobuf schemas and generate their associated python types, replacing the existing ones. - -> Note: This process has to be done only once when the Cosmos-SDK version supported by this library is changed. - -> Note: To generate python types from Cosmos-SDK protobuf schemas, you will need [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) compiler. A guide on how to install it can be found [here](https://fetchai.github.io/oef-sdk-python/user/install.html#protobuf-compiler). - -- To regenerate the protobuf schema files, run the following: - - ```bash - make proto - ``` - ->Note: For this library to be functional, only python types generated from protobuf schemas are required, not the schema files themselves. -> The schema files are fetched on-demand only to enable the generation of python types. -> Therefore, the schema files are intentionally stored as **local** files and are **NOT** checked in to this repository to minimise its filesystem footprint. - -## To set up a local Fetchai node - -To set up a local Fetchai node refer to [this guide](https://docs.fetch.ai/ledger_v2/single-node-network/). - -## To run a local Fetchai node in docker - -You require [Docker](https://docs.docker.com/get-docker/) for your platform. - -1. Place the following entrypoint script somewhere in your system (e.g `~/fetchd_docker/fetchd_initialise.sh`): - - ```bash - #!/usr/bin/env bash - - # variables - export VALIDATOR_KEY_NAME=validator - export BOB_KEY_NAME=bob - export VALIDATOR_MNEMONIC="erase weekend bid boss knee vintage goat syrup use tumble device album fortune water sweet maple kind degree toss owner crane half useless sleep" - export BOB_MNEMONIC="account snack twist chef razor sing gain birth check identify unable vendor model utility fragile stadium turtle sun sail enemy violin either keep fiction" - export PASSWORD="12345678" - export CHAIN_ID=testing - export DENOM_1=stake - export DENOM_2=atestfet - export MONIKER=some-moniker - - - # Add keys - ( echo "$VALIDATOR_MNEMONIC"; echo "$PASSWORD"; echo "$PASSWORD"; ) |fetchd keys add $VALIDATOR_KEY_NAME --recover - ( echo "$BOB_MNEMONIC"; echo "$PASSWORD"; ) |fetchd keys add $BOB_KEY_NAME --recover +When developing for `cosmpy` make sure to have the poetry shell active. This ensures that linting and formatting will automatically be checked during `git commit`. - # Configure node - fetchd init --chain-id=$CHAIN_ID $MONIKER - echo "$PASSWORD" |fetchd add-genesis-account $(fetchd keys show $VALIDATOR_KEY_NAME -a) 100000000000000000000000$DENOM_1 - echo "$PASSWORD" |fetchd add-genesis-account $(fetchd keys show $BOB_KEY_NAME -a) 100000000000000000000000$DENOM_2 - echo "$PASSWORD" |fetchd gentx $VALIDATOR_KEY_NAME 10000000000000000000000$DENOM_1 --chain-id $CHAIN_ID - fetchd collect-gentxs +We are using [Ruff](https://github.com/astral-sh/ruff) with added rules for formatting and linting. +Please consider adding `ruff` to your IDE to speed up the development process and ensure you only commit clean code. - # Enable rest-api - sed -i '/^\[api\]$/,/^\[/ s/^enable = false/enable = true/' ~/.fetchd/config/app.toml - sed -i '/^\[api\]$/,/^\[/ s/^swagger = false/swagger = true/' ~/.fetchd/config/app.toml - fetchd start - ``` +Alternately you can invoke ruff by typing the following from within the `./python` folder -2. Execute: +```bash + ruff check --fix && ruff format +``` - ```bash - docker run -it --rm --entrypoint /scripts/ -p 9090:9090 -p 1317:1317 --mount type=bind,source=,destination=/scripts/ - ``` +## Testing - where +To run tests use the following command: - - `` is the name of the entrypoint script (e.g.`fetchd_initialise.sh`) - - `` is the path to the directory you placed the script (e.g.`~/fetchd_docker/`), - - `` is the tag of the FetchD docker image you want to run (e.g. `fetchai/fetchd:0.10.0` for Dorado) +```bash + pytest +``` ## Contributing -For instructions on how to contribute to the project (e.g. creating Pull Requests, commit message convention, etc), see the [contributing guide][contributing guide]. - -[protobuf]: https://developers.google.com/protocol-buffers/ -[ipfs]: https://docs.ipfs.tech/install/ -[go]: https://golang.org/doc/install -[golines]: https://github.com/segmentio/golines -[golangci-lint]: https://golangci-lint.run -[mkdocs]: https://www.mkdocs.org -[material]: https://squidfunk.github.io/mkdocs-material/ -[poetry]: https://python-poetry.org -[contributing guide]: https://github.com/fetchai/cosmpy/blob/main/CONTRIBUTING.md -[release process]: https://github.com/fetchai/cosmpy/blob/main/scripts/RELEASE_PROCESS.md -[repo]: https://github.com/fetchai/cosmpy + +For instructions on how to contribute to the project (e.g. creating Pull Requests, commit message convention, etc), see the [contributing guide](CONTRIBUTING.md). +