vorta/CONTRIBUTING.md

Contributing

First off, thanks for taking the time to contribute!

All contributions that improve Vorta for everyone are welcome. Before coding a new feature it's usually best to discuss it with other users under Issues. Once everything is clear, follow the instructions below to

Local Development Setup

macOS (or Linux if Flatpak is not an option) with pip

Clone the latest version of this repo:

$ git clone https://github.com/borgbase/vorta/

Install in development/editable mode while in the repo root:

$ pip install -e .

Install additional developer packages (pytest, tox, pyinstaller):

pip install -r requirements.d/dev.txt

Then run as Python script. Any changes from your source folder should be reflected.

$ vorta

Linux with Flatpak

Follow the setup guide on flatpak.org to make sure you have flatpak and flathub installed.

You also need to have flatpak-builder installed, which is usually available from the same repository as the flatpak package.

Install the org.kde 5.12 runtime and SDK

$ flatpak install flathub org.kde.Platform//5.12 org.kde.Sdk//5.12

Make a repo for your local builds (If you get the error: Remote listing for my-flatpak-builds not available; server has no summary file. Check the URL passed to remote-add was valid you can ignore it):

$ mkdir ~/my-flatpak-builds
$ flatpak remote-add --user --no-gpg-verify my-flatpak-builds ~/my-flatpak-builds

Next, in Vorta’s source directory, use flatpak-builder to build a Vorta flatpak and install it (this can take more than an hour):

$ cd vorta/flatpak/
$ mkdir app
$ flatpak-builder --repo=$HOME/my-flatpak-builds app com.borgbase.Vorta.yaml
$ flatpak install --user my-flatpak-builds com.borgbase.Vorta//devel -y

Now you can work on the codebase. When you want to test your changes you can execute inside of vorta/flatpak/

$ flatpak-builder --repo=$HOME/my-flatpak-builds app com.borgbase.Vorta.yaml --force-clean && flatpak update com.borgbase.Vorta//devel -y
$ flatpak run com.borgbase.Vorta//devel 

To set which branch of Vorta (master from flathub or devel from local development setup) will be used in your OS you can use

$ flatpak make-current com.borgbase.vorta [master|devel]

Working on the GUI

Qt Creator is used to edit views. Install from their site or using Homebrew and then open the .ui files in vorta/assets/UI with Qt Creator:

$ brew cask install qt-creator
$ brew install qt

For UI icons, we use Fontawesome. You can browse available icons here and download them as SVG here. New icons are first added to both src/vorta/assets/icons/dark/collection.qrc and src/vorta/assets/icons/light/collection.qrc. Then, the command make icon-resources is run to compile them to a resource file which is used by the UI files.

Building Binaries

To build a macOS app package:

• add Sparkle.framework from here and borg from here in bin/macosx64
• then uncomment or change the Apple signing profile to be used in Makefile
• finally run to $ make Vorta.app to build the app into the dist folder.

Testing

Tests are in the folder /tests. Testing happens at the level of UI components. Calls to borg are mocked and can be replaced with some example json-output. To run tests:

$ pytest

To test for style errors:

$ flake8

Translations

Translations are updated there: https://www.Transifex.com/borgbase/vorta/

Policy for Translations

• No google translate or other automated translation.
• Only native or as-good-as-native speakers should translate.
• As there is a need for continued maintenance, a translator should be also a user of vorta, having some own interest in the translation (one-time translations are not that helpful if there is no one updating them regularly)
• A translation must have >90% translated strings. If a translation falls and stays below that for a longer time, it will not be used by vorta and ultimately, it will get removed from the repository also.

Adding a New Language

• Only add a new language if you are willing to also update the translation in future, when new strings are added and existing strings change.
• Request a new language by opening a new issue on Github. We will then add it on Transifex.

Updating a Language

• Please only work on a translation if you are a native speaker or you have similar language skills.
• Open a new issue on Github.
• Edit the language on Transifex.

Using and Testing Transifex Translations

• Extract from source files (needed after most code changes to update line number): make translations-from-source
• Push to Transifex: make translations-push
• Pull finished translations from Transifex: make translations-pull
• Compile: make translations-to-qm
• Test with specific translation: LANG=de vorta
• Scale strings to test UI: LANG=de TRANS_SCALE=200 vorta --foreground

Notes for Developers

• Original strings in .ui and .py must be American English (en_US) and ASCII.

• In English, not translated:

  • log messages (log file as well as log output on console or elsewhere)
  • other console output, print().
  • docs
  • py source code, comments, docstrings

• Translated:

  • GUI texts / messages

• In Qt (sub)classes, use self.tr("English string"), scope will be the instance class name.

• Elsewhere use vorta.i18n.translate("scopename", "English string")

• To only mark for string extraction, but not immediately translate, use vorta.i18n.trans_late function. Later, to translate, use vorta.i18n.translate (giving same scope).

Style Guide/Glossary

• Headings, buttons and dropdowns are titleized: "Apply Changes"
• Field labels (same or next line) end with a colon and are titleized. "Allowed Networks:"
• No full stop . at the end of short labels, but when it's a full sentence.
• If something is in progress, use three dots (no ellipsis): "Starting backup..."
• Repo/repository = local or remote folder where Borg stores files.
• Archive (not snapshot) = result of borg create execution, an identifier to find a collection of files in a repo, as they existed at a past point in time.

Required Software

To successfully run the translation-related Makefile targets, the translations maintainer needs:

• make tool
• pylupdate5 (from PyQt)
• lrelease (from Qt package)
• tx Transifex client (PyPI package transifex-client, contained in requirements.d/dev.txt)

Install on Debian 9 "Stretch":

$ apt install qttools5-dev-tools pyqt5-dev-tools

Install on macOS via Homebrew:

$ cd requirements.d && brew bundle