CONTRIBUTING.md 6.94 KB
Newer Older
1
2
3
4
5
# 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.

Moul's avatar
Moul committed
6
## Install the development environment
7
We are using [Poetry](https://python-poetry.org/) as a development environment solution. Start [installing Poetry](doc/install_poetry.md).
Moul's avatar
Moul committed
8
This will install a sandboxed Python environment.
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
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
```

33
Use DuniterPy as a [path dependency](https://python-poetry.org/docs/dependency-specification/#path-dependencies):
34
35
36
37
```bash
poetry add ../duniterpy
```

38
39
40
41
42
43
44
45
46
### 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.duniter.io/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)
- [Pendulum](https://pendulum.eustace.io/docs/)
- [texttable](https://github.com/foutaise/texttable/#documentation)

47
48
## Pre-commit
We are using [`pre-commit`](https://pre-commit.com/) tool to perform checks on staged changes before committing.
Moul's avatar
Moul committed
49
50
We are using it for `black` formatting, `isort` imports sorting, `pyupgrade`, and `gitlab-ci` linting.
We will use it for `pylint` code linting, `mypy` typing in the future.
51

52
Install `pre-commit` from your distribution. In case it is an outdated version, install it from `pip`:
53
54
```bash
sudo apt install pre-commit
55
pip install --user pre-commit
56
57
```

58
To install the `git-hooks`, run:
59
```bash
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
> pre-commit install
```

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

To manually run one of the tool above, run (eg for `isort`):
```bash
> pre-commit run --all-files isort
```
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](https://stackoverflow.com/a/7230886) with `git commit -m "msg" --no-verify`.
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 ""
88
```
89
Check out duniterpy#169 for more details.
90
91
92

### Black formatting
We are using [Black](https://github.com/psf/black) formatter tool.
93
Run Black on a Python file to format it:
94
95
96
```bash
poetry run black silkaj/cli.py
```
97
98
With `pre-commit`, Black is called on staged files, so the commit should fail in case black would make changes.
You will have to `git add` Black changes in order to commit your changes.
99
100

## Tests
Moul's avatar
Moul committed
101
We are using [Pytest](https://pytest.org) as a tests framework. To know more about how Silkaj implement it read the [project test documentation](doc/test_and_coverage.md).
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

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`.

124
125
126
127
128
129
130
131
132
133
134
135
136
### 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.10.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/
```

137
138
139
140
### 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`.

141
142
143
144
## 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.
145
146
147
The CD jobs does appear on a tag and have to be triggered manually.
Only the project maintainers have the rights to publish tags.

148
149
### PyPI
Publishing to PyPI from Poetry:
150
151
152
```bash
poetry publish --build
```
153
154
### PyPI test
Publishing to PyPI test from Poetry:
155
156
157
158
159
160
161
162
163
164
```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
```

165
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.
166
167
168
169
170
171
172
173
174
175
176
177
178
179

## 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
180
  - Pytest on Python supported versions
181
- PyPI distribution
182
183
  - test
  - stable