Skip to content
Snippets Groups Projects
Commit bc049a74 authored by Moul's avatar Moul
Browse files

Move changelog and contributing to `docs` folder (#433) 

Add minimal CHANGELOG.md and CONTRIBUTING.md suggesting to checkout the website
parent f41af0e7
No related branches found
No related tags found
1 merge request!271Set up new website structure with MkDocs (#433)
Expand all Hide whitespace changes
Inline Side-by-side
CHANGELOG.md
+ 2
− 748
View file @ bc049a74
This diff is collapsed.
CONTRIBUTING.md
+ 1
− 254
View file @ bc049a74
# 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](https://python-poetry.org/) as a development environment solution. Start by [installing Poetry](/install_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
<center>
[![DuniterPy logo](images/duniterpy_logo.png){: style="height:150px;width:150px"}](https://git.duniter.org/clients/python/duniterpy)
</center>
[DuniterPy](https://git.duniter.org/clients/python/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:
```bash
silkaj> cd ..
git clone https://git.duniter.org/clients/python/duniterpy
```
Use DuniterPy as a [path dependency](https://python-poetry.org/docs/dependency-specification/#path-dependencies):
```bash
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](https://clients.pages.duniter.org/python/duniterpy/index.html): Autogenerated documentation.
- Feel free to contribute upstream to share the code with other Python programs
- [Click](https://click.palletsprojects.com/#documentation)
- [Rich-Click](https://github.com/ewels/rich-click)
- [Arrow](https://arrow.readthedocs.io/)
- [texttable](https://github.com/foutaise/texttable/#documentation)
## Pre-commit hooks
<center>
[![Pre-commit logo](images/pre-commit_logo.svg){: style="height:150px;width:150px"}](https://pre-commit.com/)
</center>
We are using [`pre-commit`](https://pre-commit.com/) 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`:
```bash
sudo apt install pre-commit
pipx install pre-commit
```
To install the `git-hooks`, from within Silkaj repository, run:
```bash
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](https://stackoverflow.com/a/7230886):
```bash
git commit -m "msg" --no-verify/-n
```
To manually run one of the tool above, run (eg for `black`):
```bash
pre-commit run --all-files black
```
To run all checks on all files:
```bash
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:
```bash
export GITLAB_PRIVATE_TOKEN=""
```
With Fish, in `$HOME/.config/fish/config.fish` add the following:
```fish
set -xg GITLAB_PRIVATE_TOKEN ""
```
Check out [duniterpy#169](https://git.duniter.org/clients/python/duniterpy/-/issues/169) for more details.
## Tests
<center>
[![Pytest logo](images/pytest_logo.svg){: style="height:150px;width:150px"}](https://pytest.org)
</center>
We are using [Pytest](https://pytest.org) as a tests framework. For more information on how Silkaj implements them check the [testing documentation](/testing/).
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:
```bash
poetry run pytest
```
### How to test a single file
Specifiy the path of the test:
```bash
poetry run pytest tests/unit/test_network.py
```
## Version bump
We are using the [Semantic Versioning](https://semver.org).
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.
```bash
./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](https://pythonpackaging.info/07-Package-Release.html). i.e.: `v0.20.0rc0`.
- install a pre-release from PyPI:
```sh
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):
```sh
pip install silkaj --user --upgrade -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/
```
## Update copyright year
Follow [this documentation](https://github.com/Lucas-C/pre-commit-hooks#removing-old-license-and-replacing-it-with-a-new-one)
Only difference is to update the year in `license_header.txt` rather than `LICENSE.txt`.
## PyPI and PyPI test distributions
<center>
[![PyPI logo](images/pypi_logo.svg){: style="height:150px;width:150px"}](https://pypi.org/project/silkaj)
</center>
Silkaj is distributed to PyPI, the Python Package Index, for further `pip` installation.
Silkaj can be published to [PyPI](https://pypi.org/project/silkaj) or to [PyPI test](https://test.pypi.org/project/silkaj/) 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:
```bash
poetry publish --build
```
### PyPI test
Publishing to PyPI test from Poetry:
```bash
poetry config repositories.pypi_test https://test.pypi.org/legacy/
poetry publish --build --repository pypi_test
```
To install this package:
```bash
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
<center>
![GitLab logo](images/GitLab_icon.svg){: style="height:100px;width:100px"}
</center>
### 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](https://git.duniter.org/docker/python3/poetry).
### 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](https://git.duniter.org/documents/g1_monetary_license), 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:
```bash
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`.
Checkout the contributing guide on [Silkaj website](https://silkaj.duniter.org/latest/contributing).
docs/changelog.md deleted 120000 → 0
+ 749
− 1
View file @ f41af0e7
../CHANGELOG.md
\ No newline at end of file
docs/changelog.md 0 → 100644
+ 749
− 1
View file @ bc049a74
This diff is collapsed.
docs/contributing.md deleted 120000 → 0
+ 256
− 1
View file @ f41af0e7
../CONTRIBUTING.md
\ No newline at end of file
docs/contributing.md 0 → 100644
+ 256
− 1
View file @ bc049a74
# 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](https://python-poetry.org/) as a development environment solution. Start by [installing Poetry](/install_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
<center>
[![DuniterPy logo](images/duniterpy_logo.png){: style="height:150px;width:150px"}](https://git.duniter.org/clients/python/duniterpy)
</center>
[DuniterPy](https://git.duniter.org/clients/python/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:
```bash
silkaj> cd ..
git clone https://git.duniter.org/clients/python/duniterpy
```
Use DuniterPy as a [path dependency](https://python-poetry.org/docs/dependency-specification/#path-dependencies):
```bash
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](https://clients.pages.duniter.org/python/duniterpy/index.html): Autogenerated documentation.
- Feel free to contribute upstream to share the code with other Python programs
- [Click](https://click.palletsprojects.com/#documentation)
- [Rich-Click](https://github.com/ewels/rich-click)
- [Arrow](https://arrow.readthedocs.io/)
- [texttable](https://github.com/foutaise/texttable/#documentation)
## Pre-commit hooks
<center>
[![Pre-commit logo](images/pre-commit_logo.svg){: style="height:150px;width:150px"}](https://pre-commit.com/)
</center>
We are using [`pre-commit`](https://pre-commit.com/) 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`:
```bash
sudo apt install pre-commit
pipx install pre-commit
```
To install the `git-hooks`, from within Silkaj repository, run:
```bash
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](https://stackoverflow.com/a/7230886):
```bash
git commit -m "msg" --no-verify/-n
```
To manually run one of the tool above, run (eg for `black`):
```bash
pre-commit run --all-files black
```
To run all checks on all files:
```bash
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:
```bash
export GITLAB_PRIVATE_TOKEN=""
```
With Fish, in `$HOME/.config/fish/config.fish` add the following:
```fish
set -xg GITLAB_PRIVATE_TOKEN ""
```
Check out [duniterpy#169](https://git.duniter.org/clients/python/duniterpy/-/issues/169) for more details.
## Tests
<center>
[![Pytest logo](images/pytest_logo.svg){: style="height:150px;width:150px"}](https://pytest.org)
</center>
We are using [Pytest](https://pytest.org) as a tests framework. For more information on how Silkaj implements them check the [testing documentation](/testing/).
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:
```bash
poetry run pytest
```
### How to test a single file
Specifiy the path of the test:
```bash
poetry run pytest tests/unit/test_network.py
```
## Version bump
We are using the [Semantic Versioning](https://semver.org).
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.
```bash
./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](https://pythonpackaging.info/07-Package-Release.html). i.e.: `v0.20.0rc0`.
- install a pre-release from PyPI:
```sh
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):
```sh
pip install silkaj --user --upgrade -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/
```
## Update copyright year
Follow [this documentation](https://github.com/Lucas-C/pre-commit-hooks#removing-old-license-and-replacing-it-with-a-new-one)
Only difference is to update the year in `license_header.txt` rather than `LICENSE.txt`.
## PyPI and PyPI test distributions
<center>
[![PyPI logo](images/pypi_logo.svg){: style="height:150px;width:150px"}](https://pypi.org/project/silkaj)
</center>
Silkaj is distributed to PyPI, the Python Package Index, for further `pip` installation.
Silkaj can be published to [PyPI](https://pypi.org/project/silkaj) or to [PyPI test](https://test.pypi.org/project/silkaj/) 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:
```bash
poetry publish --build
```
### PyPI test
Publishing to PyPI test from Poetry:
```bash
poetry config repositories.pypi_test https://test.pypi.org/legacy/
poetry publish --build --repository pypi_test
```
To install this package:
```bash
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
<center>
![GitLab logo](images/GitLab_icon.svg){: style="height:100px;width:100px"}
</center>
### 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](https://git.duniter.org/docker/python3/poetry).
### 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](https://git.duniter.org/documents/g1_monetary_license), 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:
```bash
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`.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment