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.
AlgoKit development is done within the AlgoKit Guiding Principles.
-
Clone this repository:
git clone https://github.com/algorandfoundation/algokit-cli
-
Install pre-requisites:
-
Manually:
- Install
Python
- Link: The minimum required version is3.10
, but3.11
is recommended.) - Install
Poetry
- Link: The minimum required version is1.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)
- Install
-
Via AlgoKit CLI:
- Install AlgoKit CLI and run
algokit project bootstrap poetry
in the root directory - Install
tealer
- by runningpipx install tealer==0.1.2
. This is a prerequisite to runningpytest
, tealer is a third party tool for static analysis of TEAL code, algokit uses it intask analyse
command. AlgoKit usespytest-xdist
to speed up the test suite execution by running tests in parallel, this requirestealer
to be installed globally to avoid race conditions.
- Install AlgoKit CLI and run
-
-
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 runningpoetry shell
. Then executepre-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. -
Open the project and start debugging / developing via:
-
VS Code
-
Open the repository root in VS Code.
-
Install recommended extensions.
-
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)
- Open the repository root in the IDE
- Hit Shift+F9 (or whatever you have debug mapped to) and it should start running with breakpoint debugging
-
Other
- Open the repository root in your text editor of choice
- In a terminal run
poetry shell
- 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.
-
- If you update to the latest source code and there are new dependencies you will need to run
poetry install
again - Follow step 3 above
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]
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.
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: