Contributing

Goals

Part of the Duniter project running the Ğ1 currency, Silkaj project is aiming at creating a generic tool to manage the main account and wallets, to administrate and to monitor the currency.

Install the development environment

We are using Poetry as a development environment solution. Start by installing Poetry. This will install a sandboxed Python environment. Dependencies will be installed in it in order to have Silkaj running and to have pre-installed developement tools.

Workflow

• We use branches for merge requests
• We prefer fast-forward and rebase method than having merge commits created. This in order to have a clean history.

Branches

• main: development and stable branch
• maintainance branches, to maintain a stable version while developing future version with breaking changes. For instance: release/0.12

Developing with DuniterPy

DuniterPy is a Python library for Duniter v1 clients. It implements a client with multiple APIs, the handling for document signing. As it is coupled with Silkaj, it is oftenly needed to develop in both repositories.

How to use DuniterPy as editable with Poetry

Clone DuniterPy locally alongside of silkaj repository:

silkaj> cd ..
git clone https://git.duniter.org/clients/python/duniterpy

Use DuniterPy as a path dependency:

poetry add ../duniterpy

Developing with modules

Silkaj is using Python modules which shape kind of a framework. Please read their documentations on how to use them the best possible.

• DuniterPy: Autogenerated documentation.
  • Feel free to contribute upstream to share the code with other Python programs
• Click
  • Rich-Click
• Arrow
• texttable

Pre-commit hooks

We are using pre-commit tool to perform checks on staged changes before committing. We are using it for black formatting, mypy static typing, gitlab-ci linting. We are also using ruff which replaces isort imports sorting, pylint code linting, autoflake, and pyupgrade

Install pre-commit from your distribution. In case it is an outdated version, install it with pipx:

sudo apt install pre-commit
pipx install pre-commit

To install the git-hooks, from within Silkaj repository, run:

pre-commit install

Then each time you commit changes, the hooks will perform verifications.

In case you want to commit while the hooks are failing, run the following to skip the hooks:

git commit -m "msg" --no-verify/-n

To manually run one of the tool above, run (eg for ruff-format):

pre-commit run --all-files ruff-format

To run all checks on all files:

pre-commit run -a

Authorization for GitLab CI linter hook

pre-commit run -a (gitlab-ci-linter) is failing due to authorization required for CI lint API accesses. When running this command, just ignore this failed hook. In case you want to commit a .gitlab-ci.yml edition, this hook will prevent the commit creation. You can skip the hooks as mentionned above. This is fine for occasional .gitlab-ci.yml editions. In case you would like to edit this file more often and have it checked, ask a maintainer to provide you with GITLAB_PRIVATE_TOKEN environment variable that can be set into a shell configuration. With Bash, in $HOME/.bashrc add the following:

export GITLAB_PRIVATE_TOKEN=""

With Fish, in $HOME/.config/fish/config.fish add the following:

set -xg GITLAB_PRIVATE_TOKEN ""

Check out duniterpy#169 for more details.

Tests

We are using Pytest as a tests framework. For more information on how Silkaj implements them check the testing documentation.

Tests are stored into unit and integration folders depending on their types, then using a similar tree as the source code.

To run the tests, from within silkaj repository, run:

poetry run pytest

How to test a single file

Specifiy the path of the test:

poetry run pytest tests/unit/test_network.py

Version bump

We are using the Semantic Versioning.

To create a release, we use following script which will bump the version in different files, and will make a commit and a tag out of it.

./release.sh 0.20.0

Then, a git push --tags is necessary to publish the tag.

How to release a pre-release on PyPI

Append [{a|b|rc}N] to the version, it will be automatically detected as pre-release by PyPI. i.e.: v0.20.0rc0.

• install a pre-release from PyPI:

pip install silkaj --user --upgrade --pre

• install silkaj from PyPI test and the dependencies (i.e. DuniterPy) from PyPI (have been removed from the documentation):

pip install silkaj --user --upgrade -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/

Update copyright year

Follow this documentation Only difference is to update the year in license_header.txt rather than LICENSE.txt.

PyPI and PyPI test distributions

Silkaj is distributed to PyPI, the Python Package Index, for further pip installation. Silkaj can be published to PyPI or to PyPI test for testing purposes. Publishing to PyPI or PyPI test can be directly done from the continuous delivery or from Poetry it-self. The CD jobs appear on a tag and have to be triggered manually. Only the project maintainers have the rights to push tags.

PyPI

Publishing to PyPI from Poetry:

poetry publish --build

PyPI test

Publishing to PyPI test from Poetry:

poetry config repositories.pypi_test https://test.pypi.org/legacy/
poetry publish --build --repository pypi_test

To install this package:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.python.org/simple/ silkaj

The --extra-index-url is used to retrieve dependencies packages from the official PyPI not to get issues with missing or testing dependencies comming from PyPI test repositories.

Continuous integration and delivery

Own built Docker images

Silkaj pipeline is running images built on top of official Python images based on latest Debian with Poetry installed on top them.

They can be found in this repository.

Pipeline and its jobs

• Checks:
  • pre-commit hooks
  • Build
• Tests on supported Python versions:
  • Installation
  • Pytest on Python supported versions
• Package
  • PyPI stable
  • PyPI test
  • Docker pip
  • Docker poetry
• Website/project documentation commited to be deployed via GitLab Pages

Ğ1 monetary license update

To modify the Ğ1 monetary license files, please change them on its repository, since it’s integrated in silkaj repository as a git subtree.

Ğ1 monetary license is included in Silkaj repository as a git subtree. To update the licence files, add the license repository as a remote then pull:

git remote add g1_monetary_license https://git.duniter.org/documents/g1_monetary_license.git
git subtree pull --prefix g1_monetary_license g1_monetary_license master

Depending on your distribution, you might need to install git-subtree.