Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (61 loc) · 5.37 KB

CONTRIBUTING.md

File metadata and controls

91 lines (61 loc) · 5.37 KB

AlgoKit CLI for contributors

Commits

We are using the Conventional Commits standard for commit messages. This allows us to automatically generate release notes and version numbers. We do this via Python Semantic Release and GitHub actions.

Guiding Principles

AlgoKit development is done within the AlgoKit Guiding Principles.

Setup (AlgoKit CLI development)

Initial setup

  1. Clone this repository: git clone https://github.com/algorandfoundation/algokit-cli

  2. Install pre-requisites:

    • Manually:

      • Install Python - Link: The minimum required version is 3.10, but 3.11 is recommended.)
      • Install Poetry - Link: The minimum required version is 1.2.
      • If you're not using PyCharm, then run poetry install in the repository root directory (this should set up .venv and install all Python dependencies - PyCharm will do this for you on startup)

    • Via AlgoKit CLI:

      • Install AlgoKit CLI and run algokit project bootstrap poetry in the root directory
      • Install tealer - by running pipx install tealer==0.1.2. This is a prerequisite to running pytest, tealer is a third party tool for static analysis of TEAL code, algokit uses it in task analyse command. AlgoKit uses pytest-xdist to speed up the test suite execution by running tests in parallel, this requires tealer to be installed globally to avoid race conditions.

  3. Install pre-commit hooks (optional but recommended):

    pre-commit is configured in this repository. To enable it, make sure that poetry install has been run and the virtual-env is activated by running poetry shell. Then execute pre-commit install to install the git hook scripts.

    Once it is done, git will ensure formatting, linting, and static typing (via mypy) is correct when you perform a commit.

  4. Open the project and start debugging / developing via:

    • VS Code

      1. Open the repository root in VS Code.

      2. Install recommended extensions.

      3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.

        Note The first time you run, VS Code may prompt you to select the Python Interpreter, or if you are having issues running you may need to select it via the Python: Select Interpreter pallette command. You should select the Python Interpreter with the ./.venv path)

    • IDEA (e.g. PyCharm)

      1. Open the repository root in the IDE
      2. Hit Shift+F9 (or whatever you have debug mapped to) and it should start running with breakpoint debugging

    • Other

      1. Open the repository root in your text editor of choice
      2. In a terminal run poetry shell
      3. Run ./debug.py through your debugger of choice

    • In each of the above cases, an args.in file will be created in the source root. Each line will be executed in order, with the arguments passed to the cli. For example, you could have:

      version
--help
version --help

      Not a terribly useful sequence of commands, but hopefully this helps illustrate the usage.

Subsequently

  1. If you update to the latest source code and there are new dependencies you will need to run poetry install again
  2. Follow step 3 above

Documentation

Markdown documentation can be found within the docs directory of the repo, there is a mixture of handwritten documentation and autogenerated documentation for the CLI tool itself. To autogenerate the CLI documentation from the click source execute poe docs, note: this command won't work on Windows.

The CLI docs are generated using Sphinx, and its configuration can be found in docs\sphinx. The generated Markdown output is post processed to add a Table of Contents and top level title and the final Markdown is output to docs\cli. The commands to achieve this are defined in pyproject.toml under [tool.poe.tasks]

Libraries and Tools

AlgoKit uses Python as a main language and many Python libraries and tools. This section lists all of them with a tiny brief.

  • Poetry: Python packaging and dependency management.
  • pipx: Install and Run Python Applications in Isolated Environments
  • Click: A Python package for creating beautiful command line interfaces.
  • Black: A Python code formatter.
  • Tox: Automate and standardize testing in Python.

Architecture decisions

As part of developing AlgoKit we are documenting key architecture decisions using Architecture Decision Records (ADRs). The following are the key decisions that have been made thus far: