diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 120000 index 9308b99b2f20ecca057b9bc24349c645d4c4834b..0000000000000000000000000000000000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -doc/contributing.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..2b3a87402a0dd7c66a5dd4466b64f9ebccf1a1bc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,127 @@ +# Contributing + +## Goals +Part of the Duniter project running the Äž1 currency, Silkaj project is aiming to create a generic tool to manage his account and wallets, and to monitor the currency. + +## Install the development environement +We are using [Poetry](https://poetry.eustace.io/) as a development environement solution. Start [installing Poetry](install_poetry.md). +This will install a sandboxed Python environement. +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 a merge commit. This in order to have a clean history. + +## Branches +- `master` branch as stable +- maintainance branches, to maintain a stable version while developing future version with breaking changes. For instance: `0.7` +- `dev` branch + +## Developing with DuniterPy +[DuniterPy](https://git.duniter.org/clients/python/duniterpy) is a Python library for Duniter 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://poetry.eustace.io/docs/versions/#path-dependencies): +```bash +poetry add ../duniterpy +``` + +## Formatting +We are using [Black](https://github.com/python/black) as a formatter tool. + +Black is not in the development dependencies in order to keep Python 3.5 support. +There is three way you can install Black: +- From your package manager. i.e. Debian Buster: `sudo apt install black` +- On your machine via `pip`: `pip3 install black --user` +- In your Poetry virtualenv: +To have it installed in your Poetry virtualenv, you need Python v3.6 or greater. +In the `pyproject.toml` pass the Python requirement version from "3.5.x" to "3.6". +Then, install it with `poetry add black --dev`. + +Once installed in your development environement, run Black on a Python file to format it: +```bash +poetry run black silkaj/cli.py +``` + +### Pre-commit +Then, you can use the `pre-commit` tool to check staged changes before committing. +To do so, you need to run `pre-commit install` to install the git hook. +Black is called on staged files, so commit should fail in case black made changes. +You will have to add Black changes in order to commit your changes. + +## Tests +We are using [Pytest](https://pytest.org) as a tests framework. To know more about how Silkaj implement it read the [project test documentation](test_and_coverage.md). + +To run tests, within `silkaj` repository: +```bash +poetry run pytest +``` + +### How to test a single file +Specifiy the path of the test: +```bash +poetry run pytest tests/test_end_to_end.py +``` + +## Version update +We are using the [Semantic Versioning](https://semver.org). + +To create a release, we use following script which will update the version in different files, and will make a commit and a tag out of it. +```bash +./release.sh 0.8.1 +``` + +Then, a `git push --tags` is necessary to publish the tag. Git could be configured to publish tags with a simple `push`. + +## PyPi and PyPi test distributions +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 does appear on a tag and have to be triggered manually. +Only the project maintainers have the rights to publish 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 +### Own built Docker images +- https://git.duniter.org/docker/python3/poetry +- Python images based on Debian Buster +- Poetry installed on top +- Black installed on v3.8 + +### Jobs +- Checks: + - Format + - Build +- Tests on supported Python versions: + - Installation + - Pytest for v3.5, 3.6, 3.7, and 3.8 +- PyPi distribution + - test + - stable diff --git a/doc/contributing.md b/doc/contributing.md deleted file mode 100644 index 2b3a87402a0dd7c66a5dd4466b64f9ebccf1a1bc..0000000000000000000000000000000000000000 --- a/doc/contributing.md +++ /dev/null @@ -1,127 +0,0 @@ -# Contributing - -## Goals -Part of the Duniter project running the Äž1 currency, Silkaj project is aiming to create a generic tool to manage his account and wallets, and to monitor the currency. - -## Install the development environement -We are using [Poetry](https://poetry.eustace.io/) as a development environement solution. Start [installing Poetry](install_poetry.md). -This will install a sandboxed Python environement. -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 a merge commit. This in order to have a clean history. - -## Branches -- `master` branch as stable -- maintainance branches, to maintain a stable version while developing future version with breaking changes. For instance: `0.7` -- `dev` branch - -## Developing with DuniterPy -[DuniterPy](https://git.duniter.org/clients/python/duniterpy) is a Python library for Duniter 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://poetry.eustace.io/docs/versions/#path-dependencies): -```bash -poetry add ../duniterpy -``` - -## Formatting -We are using [Black](https://github.com/python/black) as a formatter tool. - -Black is not in the development dependencies in order to keep Python 3.5 support. -There is three way you can install Black: -- From your package manager. i.e. Debian Buster: `sudo apt install black` -- On your machine via `pip`: `pip3 install black --user` -- In your Poetry virtualenv: -To have it installed in your Poetry virtualenv, you need Python v3.6 or greater. -In the `pyproject.toml` pass the Python requirement version from "3.5.x" to "3.6". -Then, install it with `poetry add black --dev`. - -Once installed in your development environement, run Black on a Python file to format it: -```bash -poetry run black silkaj/cli.py -``` - -### Pre-commit -Then, you can use the `pre-commit` tool to check staged changes before committing. -To do so, you need to run `pre-commit install` to install the git hook. -Black is called on staged files, so commit should fail in case black made changes. -You will have to add Black changes in order to commit your changes. - -## Tests -We are using [Pytest](https://pytest.org) as a tests framework. To know more about how Silkaj implement it read the [project test documentation](test_and_coverage.md). - -To run tests, within `silkaj` repository: -```bash -poetry run pytest -``` - -### How to test a single file -Specifiy the path of the test: -```bash -poetry run pytest tests/test_end_to_end.py -``` - -## Version update -We are using the [Semantic Versioning](https://semver.org). - -To create a release, we use following script which will update the version in different files, and will make a commit and a tag out of it. -```bash -./release.sh 0.8.1 -``` - -Then, a `git push --tags` is necessary to publish the tag. Git could be configured to publish tags with a simple `push`. - -## PyPi and PyPi test distributions -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 does appear on a tag and have to be triggered manually. -Only the project maintainers have the rights to publish 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 -### Own built Docker images -- https://git.duniter.org/docker/python3/poetry -- Python images based on Debian Buster -- Poetry installed on top -- Black installed on v3.8 - -### Jobs -- Checks: - - Format - - Build -- Tests on supported Python versions: - - Installation - - Pytest for v3.5, 3.6, 3.7, and 3.8 -- PyPi distribution - - test - - stable