mirror of
https://github.com/borgbase/vorta
synced 2025-01-03 05:36:19 +00:00
Remove redundant docs from repo and link to new website. (#334)
* Remove redundant docs from repo and link to new website. * Reduce Matrix advertising a bit. * Remove first website link.
This commit is contained in:
Manuel Riel
GitHub
parent
1bb780897c
commit
d86bbf1cbd
3 changed files with 4 additions and 222 deletions
183
CONTRIBUTING.md
183
CONTRIBUTING.md
|
|
@ -1,183 +0,0 @@
|
||||||
# Contributing
|
|
||||||
[](https://travis-ci.org/borgbase/vorta)
|
|
||||||
|
|
||||||
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](https://github.com/borgbase/vorta/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](http://flatpak.org/setup/) 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](https://www.qt.io/download) 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](https://fontawesome.com/icons) and download them as SVG [here](https://github.com/encharm/Font-Awesome-SVG-PNG). 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](https://github.com/sparkle-project/Sparkle) and `borg` from [here](https://github.com/borgbackup/borg/releases) 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
|
|
||||||
```
|
|
||||||
25
INSTALL.md
25
INSTALL.md
|
|
@ -1,25 +0,0 @@
|
||||||
# Installing
|
|
||||||
|
|
||||||
|
|
||||||
## Install from Source
|
|
||||||
The generic way is to install it as Python package using [PIP](https://pip.readthedocs.io/en/stable/installing/). First [install](https://borgbackup.readthedocs.io/en/stable/installation.html) Borg using the package of your distribution or via PyPI. The latter needs some additional [source packages](https://borgbackup.readthedocs.io/en/stable/installation.html#dependencies). Then install Vorta from PyPI. Your local Python version should be >= 3.6.
|
|
||||||
```
|
|
||||||
$ pip3 install vorta
|
|
||||||
```
|
|
||||||
|
|
||||||
### Desktop Tray Icon
|
|
||||||
Unless Vorta is started with the `--foreground` option, it will minimize to the system tray without opening a settings window. Be sure your desktop environment supports tray icons by e.g. installing this [Gnome extension](https://extensions.gnome.org/extension/615/appindicator-support/).
|
|
||||||
|
|
||||||
## Distribution Packages
|
|
||||||
If available, prefer distribution-specific packages, as they offer better integration. (If you added Vorta to a Linux distribution, open an issue or PR and it will be added here.)
|
|
||||||
|
|
||||||
### Apple macOS
|
|
||||||
Install via [Homebrew Cask](https://brew.sh/) or download a pre-built app bundle for macOS (10.13+) from [Releases](https://github.com/borgbase/vorta/releases).
|
|
||||||
```
|
|
||||||
$ brew cask install vorta
|
|
||||||
```
|
|
||||||
### Arch Linux
|
|
||||||
Use the [AUR package](https://aur.archlinux.org/packages/vorta/) maintained by [@bjo81](https://github.com/bjo81).
|
|
||||||
```
|
|
||||||
$ yaourt -S vorta
|
|
||||||
```
|
|
||||||
18
README.md
18
README.md
|
|
@ -12,27 +12,17 @@ Vorta is a backup client for macOS and Linux desktops. It integrates the mighty
|
||||||
- **Flexible profiles** to group source folders, backup destinations and schedules.
|
- **Flexible profiles** to group source folders, backup destinations and schedules.
|
||||||
- **One place** to view all point-in-time archives and restore individual files.
|
- **One place** to view all point-in-time archives and restore individual files.
|
||||||
|
|
||||||
|
Learn more on [Vorta's website](https://vorta.borgbase.com).
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
Vorta should work on all platforms that support Qt and Borg. This includes macOS, Ubuntu, Debian, Fedora, Arch Linux and many others. Windows is currently not supported by Borg, but this may change in the future.
|
Vorta should work on all platforms that support Qt and Borg. This includes macOS, Ubuntu, Debian, Fedora, Arch Linux and many others. Windows is currently not supported by Borg, but this may change in the future.
|
||||||
|
|
||||||
For available packages and instructions, see [INSTALL.md](https://github.com/borgbase/vorta/blob/master/INSTALL.md)
|
See our website for [download links and and install instructions](https://vorta.borgbase.com/download).
|
||||||
|
|
||||||
|
|
||||||
## Learn More
|
|
||||||
- [Description](https://borgbackup.readthedocs.io/en/stable/internals.html) of Borg's internal workings and security
|
|
||||||
- [High level guide and template](https://docs.borgbase.com/backup-strategy/steps-with-template/) on setting up a complete backup strategy
|
|
||||||
- [Detailed tutorial](https://docs.borgbase.com/macos/how-to-backup-your-mac-using-the-vorta-backup-gui/) on setting up Vorta
|
|
||||||
- Why the name? [Vorta](http://memory-alpha.wikia.com/wiki/Vorta) are a race referenced in Star Trek. After dying they are replaced by their cloned backup.
|
|
||||||
|
|
||||||
|
|
||||||
## Development and Bugs
|
## Development and Bugs
|
||||||
- Report bugs and submit feature ideas by opening a new [Github issue](https://github.com/borgbase/vorta/issues/new/choose).
|
- Report bugs and submit feature ideas by opening a new [Github issue](https://github.com/borgbase/vorta/issues/new/choose).
|
||||||
- Want to contribute to Vorta? Great! See [CONTRIBUTING.md](https://github.com/borgbase/vorta/blob/master/CONTRIBUTING.md)
|
- Want to contribute to Vorta? Great! See our [contributor guide](https://vorta.borgbase.com/contributing/) on how to help out with coding, translation and packaging.
|
||||||
|
- If you have questions or simply want to talk about Vorta, find us on [Matrix](https://matrix.to/#/#vorta:matrix.org). For Borg-specific topics, join the `#borgbackup` IRC channel on `chat.freenode.net` instead.
|
||||||
## Get in touch
|
|
||||||
- If you have questions or simply want to talk about Vorta hit us up at [Matrix](https://matrix.to/#/#vorta:matrix.org)
|
|
||||||
- If your questions are Borg-specific it might be advisable to join the #borgbackup IRC channel on chat.freenode.net instead. Matrix is very suitable to be used as an always-on IRC-client, simply [register/identify to NickServ](https://github.com/matrix-org/matrix-appservice-irc/wiki/End-user-FAQ#how-do-i-registeridentify-to-nickserv) and then join the room `#freenode_#borgbackup:matrix.org`.
|
|
||||||
|
|
||||||
## License and Credits
|
## License and Credits
|
||||||
- Thank you to all the people who already contributed to Vorta: [code](https://github.com/borgbase/vorta/graphs/contributors), [translations](https://github.com/borgbase/vorta/issues/159)
|
- Thank you to all the people who already contributed to Vorta: [code](https://github.com/borgbase/vorta/graphs/contributors), [translations](https://github.com/borgbase/vorta/issues/159)
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue