Commit dca5cbef authored by Jerome Flesch's avatar Jerome Flesch

Merge branch 'testing' into develop

parents 64cee09b 7ad9df33
Pipeline #129435 failed with stages
in 10 minutes and 37 seconds
# How to contribute ?
[You can help in many way](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contributing):
- Code contributions
- UX and UI designs
[You can help in many ways](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contributing):
- [Code contributions](doc/install.devel.markdown)
- UX and UI designs ([example](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/issues/356#note_244099))
- Testing
- Translating
- Documentation
- 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)
For most tasks, being familiar with Git is really helpful.
Most of the communication happens on the [bug tracker](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/issues).
Sometimes the [mailing-list](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contact#mailing-list)
or [IRC](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/wikis/Contact#irc) are used too.
# Code contribution rules
......@@ -13,15 +20,17 @@
* All commits go to the branch 'develop'. I (Jflesch) will cherry-pick them in master or release branches if required.
* Paperwork is made to be *simple* to use (think simple enough that your own grandmother could install and use it)
* Paperwork is open-source software (GPLv3+)
* 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)
* 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)
* You must not break existing features. You're strongly encouraged to discuss the changes you want to make beforehand (on the bug tracker, the mailing-list or IRC).
* 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)
* If you make an important contribution, please try to maintain it (fix bug reported by other users regarding features you added, etc).
* Unmaintained and unmaintainable pieces of code will be removed, sooner or later.
* [Please try to have one change per commit](https://www.freshconsulting.com/atomic-commits/).
* 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.
* 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.
* If you add new dependencies, please update:
* `setup.py`: for Python dependencies
* `setup_cx_freeze.py`: for the build of the Windows executable (only for the GTK interface)
* `src/paperwork/deps.py`: frontend ; for non-Python dependencies
* `paperwork-backend/deps.py`: backend ; for non-Python dependencies
* `flatpak/develop.json`: Used to generate Flatpak packages (see `flatpak-builder`). To test your changes, you can generate standalone Paperwork Flatpak bundles with "cd flatpak ; make bundles" (it's quite long ; beware it will use your local `develop.json` but will package Paperwork from Github).
......@@ -33,29 +42,55 @@ 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
(again, please run "make check" before submitting a change)
(again, please run `make check` before submitting a change)
# Continous Integration
# Continous Integration and Delivery
There is a [BuildBot](https://origami.openpaper.work). Between your machine and Buildbot, Buildbot is always right.
There is a [Continous Integration and Delivery](https://origami.openpaper.work) running.
All changes must leave the CI/CD OK.
# Branches
Paperwork follows a process similar to the [GitFlow branching model](http://nvie.com/posts/a-successful-git-branching-model/).
Permanent branch:
* 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.
Semi-permanent branches:
* release-xxxx : the next version of Paperwork, during its testing phase. No new feature is allowed. Only bugfixes, translations and documentation updates.
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.
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)
Temporary / feature development branches:
* wip-xxxx
* `wip-xxxx`
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
Paperwork maintainer (Jerome Flesch).
# Tips
Bugfixes and other contributions usually go in the branch 'develop'. They may or may not be cherry-picked into the branches release-xxx and master by Paperwork maintainer (Jerome Flesch).
## Debug
You can use the environment variable `PAPERWORK\_VERBOSE` to increase or
decrease the logging level. The accepted values are: DEBUG, INFO, WARNING,
ERROR.
## 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:
Paperwork looks for a file `paperwork.conf` in the current work directory before
looking for a `.paperwork.conf` in your home directory. So if you want to
use a different configuration and/or a different set of documents for development
than for your real-life work, just copy your `~/.paperwork.conf` to
`./paperwork.conf`. Note that the settings dialog will also take care of
updating `./paperwork.conf` instead of `~/.paperwork.conf` if it exists.
# Versionning
......@@ -82,28 +117,4 @@ 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).
If extra == "git", indicates a version directly taken from the git repository.
# Tips
## Debug
You can use the environment variable `PAPERWORK\_VERBOSE` to increase or
decrease the logging level. The accepted values are: DEBUG, INFO, WARNING,
ERROR.
## 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:
Paperwork looks for a file `paperwork.conf` in the current work directory before
looking for a `.paperwork.conf` in your home directory. So if you want to
use a different configuration and/or a different set of documents for development
than for your real-life work, just copy your `~/.paperwork.conf` to
`./paperwork.conf`. Note that the settings dialog will also take care of
updating `./paperwork.conf` instead of `~/.paperwork.conf` if it exists.
If extra == "git", indicates a version directly taken from the git repository.
\ No newline at end of file
......@@ -3,26 +3,33 @@
## Build dependencies
It's hard to list all the dependencies here. Currently, the main ones are:
Paperwork build is based on [Msys2](https://www.msys2.org/).
* [Msys2](https://www.msys2.org/)
* [Python 3.4](https://www.python.org/downloads/windows/)
* GObject Introspection, Gtk, Gdk, Libpoppler, & friends
* GNU Makefile
You can have a look at the
[.gitlab-ci.yml](https://gitlab.gnome.org/World/OpenPaperwork/paperwork/blob/develop/.gitlab-ci.yml)
(target 'windows_exe') to have an exhaustive list of all the required MSYS2 packages.
Some Python packages are automatically downloaded and installed by setuptools when running
`make install` / `make install_py` / `python3 ./setup.py install` / etc.
They must be installed *before* the rest of Paperwork. Once everything is installed:
Once everything is installed:
* [Clone](https://git-for-windows.github.io/) ```https://gitlab.gnome.org/World/OpenPaperwork/paperwork.git```
* You can run ```make install``` (GNU Makefile) to fetch all the Python dependencies
not listed here. However, it won't create any shortcut or anything. Paperwork startup script
is installed, but isn't of much help.
* `git clone https://gitlab.gnome.org/World/OpenPaperwork/paperwork.git`
* You can run `make install` (GNU Makefile) to fetch all the Python dependencies
not listed here and install Paperwork system-wide. However, it won't create
any shortcut or anything (the installer creates them).
Tesseract is not packaged in the same .zip than Paperwork and is not required
to build Paperwork executable and .zip. It is only required for running it.
Already-compiled version of Tesseract and its data files are available on
[download.openpaper.work](https://download.openpaper.work/tesseract/) and are
the files actually downloaded by the installer.
## Running
Go to where you checked out Paperwork frontend,
and run ```python paperwork\src\launcher.py```. Tesseract must be in your PATH.
and run ```python3 paperwork\src\launcher.py```. Tesseract must be in your PATH.
## Packaging
......@@ -74,4 +81,4 @@ C:\Program Files (x86)\OpenPaper\ (for example)
|-- fra.traineddata
```
Note that it will only work if packaged with Pyinstaller.
Note that it will only work if packaged with cx_freeze (`sys.frozen == True`).
## Branches
* branch `master` is the latest release with possibly some bug fixes. Never
submit a merge request for this branch. Only Paperwork maintainer(s)
push changes on this branch.
* branch 'develop' is the development branch. It will be the next version
of Paperwork. Merge request should always go to this branch, even for bug
fixes. Maintainer(s) will cherry-pick commits in the branch 'master' if
required.
`
## Contributing
Please read [CONTRIBUTING.md](CONTRIBUTING.md) carefully before submitting any
merge request.
## Paperwork in a Virtualenv
......
Markdown is supported
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