CONTRIBUTING.md 8.08 KB
Newer Older
Jerome Flesch's avatar
Jerome Flesch committed
1
2
3
4
5
6
7
8
9
10
# Reporting bug

If you want open a ticket on Gitlab, the following information is needed:
- Exact Paperwork version
- Operation system (Windows ? Linux ?)
- If you use Linux: how did you install Paperwork ? Using Flatpak ?
- Logs of the session where the bug happened are strongly recommended.
- If the bug is a UI bug, a screenshot is strongly recommended.

# Other contributions
Jerome Flesch's avatar
Jerome Flesch committed
11

12
[You can help in many ways](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contributing):
Jerome Flesch's avatar
Jerome Flesch committed
13
- [Code contributions](doc/install.devel.markdown)
Jerome Flesch's avatar
Jerome Flesch committed
14
- UX and UI designs ([example](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/issues/356#note_244099))
Jerome Flesch's avatar
Jerome Flesch committed
15
- Testing
Jerome Flesch's avatar
Jerome Flesch committed
16
- [Translating](https://translations.openpaper.work)
Jerome Flesch's avatar
Jerome Flesch committed
17
18
- Documentation (markdown files or [LyX](https://www.lyx.org/)/[PDF files](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/tree/master/paperwork-gtk/doc)
  integrated in Paperwork)
Jerome Flesch's avatar
Jerome Flesch committed
19

Jerome Flesch's avatar
Jerome Flesch committed
20
21
For most tasks, being familiar with Git is really helpful.

Jerome Flesch's avatar
Jerome Flesch committed
22
23
24
25
Most of the communication happens on the
[bug tracker](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/issues)
or on the [forum](https://forum.openpaper.work/)
Sometimes [IRC](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contact#irc) is used too.
26

Jerome Flesch's avatar
Jerome Flesch committed
27

28
29
30
# Code contribution

Rules are:
Jerome Flesch's avatar
Jerome Flesch committed
31

32
* All commits go to the branch `develop`. I (Jflesch) will cherry-pick them in the branches `master` (stable) or `testing` (release) if required.
Jerome Flesch's avatar
Jerome Flesch committed
33
* Paperwork is made to be *simple* to use (think simple enough that your own mother could install and use it)
Jerome Flesch's avatar
Jerome Flesch committed
34
* Paperwork is open-source software (GPLv3+)
35
* Run `make check` and `make test`. If they fail, your changes will be rejected.
Jerome Flesch's avatar
Jerome Flesch committed
36
37
* Consider adding automated tests.
* Consider updating the user manual
38
  (paperwork-gtk/src/paperwork\_gtk/model/help/data/\*.tex)
Jerome Flesch's avatar
Jerome Flesch committed
39
* Your changes must respect the [PEP8](https://www.python.org/dev/peps/pep-0008/): you can use the command `make check` to check your changes
40
41
* You must not break existing features.
* You're strongly encouraged to discuss the changes you want to make beforehand (on the bug tracker, on the forum or on IRC).
Jerome Flesch's avatar
Jerome Flesch committed
42
43
* Your contribution must be maintainable: It must be clear enough so that somebody else can maintain it. If it is a complicated piece of code, please comment it as clearly as possible.
* Your contribution must and will be reviewed (most likely by me, Jflesch)
Jerome Flesch's avatar
Jerome Flesch committed
44
* If you make an important contribution, please try to maintain it (fix bugs reported by other users regarding features you added, etc).
Jerome Flesch's avatar
Jerome Flesch committed
45
* Unmaintained and unmaintainable pieces of code will be removed, sooner or later.
Jerome Flesch's avatar
Jerome Flesch committed
46
* [Please try to have one change per commit](https://www.freshconsulting.com/atomic-commits/).
Jerome Flesch's avatar
Jerome Flesch committed
47
* If you see pieces of code that doesn't follow these rules, feel free to make a cleanup commit to fix it. Please do not mix cleanups with other changes in a same commit.
Jerome Flesch's avatar
Jerome Flesch committed
48
* If you add new dependencies, please update:
Jerome Flesch's avatar
Jerome Flesch committed
49
50
51
  * setup.py scripts as required (beware of Windows support)
  * `chkdeps()` methods as required
  * Flatpak JSON files as required
Jerome Flesch's avatar
Jerome Flesch committed
52

53
Same rules apply for all the libraries in Openpaperwork: PyOCR, Libinsane, etc.
Jerome Flesch's avatar
Jerome Flesch committed
54
55
56
57
58
59
60

Regarding PEP-8, the following rules must be strictly followed:

1. Lines are at most 80 characters long
2. Indentation is done using 4 spaces


Jerome Flesch's avatar
Jerome Flesch committed
61
# Continous Integration and Delivery
Jerome Flesch's avatar
Jerome Flesch committed
62

Jerome Flesch's avatar
Jerome Flesch committed
63
64
65
There is a [Continous Integration and Delivery](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/pipelines) running.
All changes must leave the CI/CD OK. You can have look at the file
.gitlab-ci.yml to know what the CI/CD build and check.
Jerome Flesch's avatar
Jerome Flesch committed
66
67
68
69
70
71


# Branches

Paperwork follows a process similar to the [GitFlow branching model](http://nvie.com/posts/a-successful-git-branching-model/).

72
73
74
75
76
Permanent branches:
* `master` : always match the last released version of Paperwork + some extra bugfixes. Only documentation updates and **safe** bugfixes are allowed on this branch. Minor versions come from this branch.
  Please **do not** send me changes for the branch 'master'. Send them for the branch `develop`, and I will cherry-pick them on `master` if required.
* `develop` : where new features, cleanup, etc go.
* `testing` : the next version of Paperwork, during its testing phase. No new feature is allowed. Only bugfixes, translations and documentation updates.
Jerome Flesch's avatar
Jerome Flesch committed
77
78
  When no new version is being prepared, it simply matches the branch `master`. (Those pre-release branches should be called `release-xxx`, but here it's
  called `testing` to simplify CI/CD management)
Jerome Flesch's avatar
Jerome Flesch committed
79
80

Temporary / feature development branches:
81
* `wip-xxxx`
Jerome Flesch's avatar
Jerome Flesch committed
82

Jerome Flesch's avatar
Jerome Flesch committed
83
84
Bug fixes and other contributions always go first in the branch `develop`.
They may or may not be cherry-picked into the branches `testing` and `master` by
85
Paperwork maintainer (Jerome Flesch).
Jerome Flesch's avatar
Jerome Flesch committed
86

87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
# Main dependencies

Paperwork depends on various libraries:

* GLib, Cairo, GTK, etc: GUI
* Poppler: Reading PDF
* Pillow: Reading images, basic operations on images, writing images
* [PyOCR](https://gitlab.gnome.org/World/OpenPaperwork/pyocr):
  Wrapper for Tesseract + Parsing and writing of hOCR files
* [Libpillowfight](https://gitlab.gnome.org/World/OpenPaperwork/libpillowfight):
  Various image processing algorithms
* [Libinsane](https://gitlab.gnome.org/World/OpenPaperwork/libinsane):
  Crossplatform access to scanners

# General code structure

Paperwork is divided in many Python packages:

Jerome Flesch's avatar
Jerome Flesch committed
105
* openpaperwork-core [[doc]](https://doc.openpaper.work/openpaperwork_core/latest/index.html). It contains:
Jerome Flesch's avatar
Jerome Flesch committed
106
  - The core itself. The core is the piece
107
108
109
110
111
112
113
    of code that manages the plugins. It's designed to be as minimal as possible.
  - Various plugins who could be useful in pretty much any other application,
   GUI or not (for instance, [Pythoness](https://framagit.org/OpenPaperwork/pythoness)).
* openpaperwork-gtk:
  - Various plugins who could be useful in pretty much any Gnome/GTK application
    (for instance, [Pythoness](https://framagit.org/OpenPaperwork/pythoness)).
* paperwork-backend:
Jerome Flesch's avatar
Jerome Flesch committed
114
  - Plugins for Paperwork independent from any type of frontends (plugins to manage the
115
116
117
118
119
    work directory, provide various features, access scanners, etc)
* paperwork-gtk:
  - Plugins and bootstrap module that compose the GTK user interface of Paperwork
* paperwork-shell:
  - Plugins and bootstrap module that compose the shell interface (CLI or JSON)
Jerome Flesch's avatar
Jerome Flesch committed
120

Jerome Flesch's avatar
Jerome Flesch committed
121
122
# Tips

123
124
125
126
127
128
129
130
131
132
133
134
## Virtual env

You can easily get a Python virtual environment that includes OpenPaperwork
dependencies (Libinsane, ...) by using the script `activate_test_env.sh`:

```sh
make clean  # delete any previously existing virtual env
source ./activate_test_env.sh  # build and load a virtual env
make install # install Paperwork and its Python dependencies in the virtual env
paperwork-gtk
```

Jerome Flesch's avatar
Jerome Flesch committed
135
136
137

## Debug

138
139
140
141
142
143
144
145
146
147
148
149
150
On GNU/Linux, you can increase debug level by using the following command:

```sh
paperwork-gtk config put log_level str debug
```

Or, if you use Flatpak:

```sh
flatpak run --command=paperwork-gtk work.openpaper.Paperwork config put log_level str debug
```

You can revert the log level by setting it back to `info` instead of `debug`.
Jerome Flesch's avatar
Jerome Flesch committed
151
152
153
154
155
156


## Separate Paperwork configuration for development from your day-to-day configuration

If you want to make changes, here is a tip that can help you:

157
158
Paperwork looks for a file `paperwork2.conf` in the current work directory before
looking for a `~/.config/paperwork2.conf` in your home directory. So if you want to
Jerome Flesch's avatar
Jerome Flesch committed
159
use a different configuration and/or a different set of documents for development
160
161
162
than for your real-life work, just copy your `~/.config/paperwork2.conf` to
`./paperwork2.conf`. Note that the settings dialog will also take care of
updating `./paperwork2.conf` instead of `~/.config/paperwork2.conf` if it exists.
Jerome Flesch's avatar
Jerome Flesch committed
163
164


Jerome Flesch's avatar
Jerome Flesch committed
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
# Versionning

Version have the following syntax: <M>[.<m>[.<U>[-<extra>]]]

## M = Major version

Major changes made / product completed.

On libraries, it means completely incompatible API with the previous version.

## m = minor version

Minor changes made.

On libraries, it means new major features have been added, but API should remain compatible.

## U = update version

Only bugfixes or very minor features.


## Extra

May match a Git tag done before a big change (for instance: before switching from Gtk 2 to Gtk 3).
Jerome Flesch's avatar
Jerome Flesch committed
189
If extra == "git", indicates a version directly taken from the git repository.