Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
507 lines (414 loc) · 23 KB

CONTRIBUTING.md

File metadata and controls

507 lines (414 loc) · 23 KB

How to contribute to Back In Time

😊 Thanks for taking the time to contribute. 😊

🟢 Contributions can be much more than code. 🟢

The maintenance team welcomes all types of contributions. No contribution will be rejected solely because it doesn't meet our quality standards, guidelines, or rules. Every contribution is reviewed, and if necessary, improved in collaboration with the maintenance team. New contributors who may need assistance or are less experienced are warmly welcomed and will be mentored by the maintenance team upon request.

There are many ways to contribute beyond coding: translating the project, performing manual tests, analyzing and reproducing bugs, reviewing and testing pull requests, providing feedback on new features, designing an application logo, or reviewing the documentation and suggesting improvements. 🚀 Every contribution helps the project grow! 🚀

Index

Quick guide

Important

Please remember to create a new branch before you begin any modifications. Baseline your feature or bug fix branch on dev (reflecting the latest development state).

  1. Fork this repository. See Microsoft GitHub's own documentation about how to fork.

  2. Clone your own fork to your local machine and enter the directory:

    $ git clone git@github.com:YOURNAME/backintime.git
$ cd backintime

  3. Create and checkout your own feature or bugfix branch with dev as baseline branch:

    $ git checkout -b myfancyfeature dev

  4. Now you can add your modifications.

  5. Commit and push it to your forked repo:

     $ git commit -am 'commit message'
 $ git push

  6. Test your modifications. See section Build & Install and Testing for further details.

  7. Visit your own repository on Microsoft GitHub's website and create a Pull Request. See Microsoft GitHub's own documentation about how to create a Pull Request based on your own fork.

Best practice and recommendations

If possible, please consider the following best practices. This will reduce the workload of the maintainers and increase the chances of your pull request being accepted.

  • Follow PEP 8 as a minimal Style Guide for Python Code.
  • About strings:
    • Prefer single quotes (e.g. 'Hello World') over double qutoes (e.g. "Hello World"). Exceptions are when single quotes contained in the string (e.g. "Can't unmount").
    • Enclose translatable strings like this: _('Translate me'). Find more details in our localization docu.
  • For docstrings follow Google Style Guide (see our own HOWTO about doc generation).
  • Avoid the use of automatic formatters like black but mention the use of them when opening a pull request.
  • Run unit tests before you open a pull request. You can run them via make-system with cd common && ./configure && make && make test or using a regular unittest runner of your choice (e.g. pytest). See section Build and install via make system for further details.
  • Try to create new unit tests if appropriate. Use the style of regular Python unittest rather than pytest. If you know the difference, please try to follow the Classical (aka Detroit) school instead of London (aka mockist) school.
  • See recommendations about how to handle translatable strings.

Resources & Further readings

Build & Install

This section describes how to build and install Back In Time in preparation of your own contributions. It is assumed that you git clone this repository first.

Dependencies

The following dependencies are based on Debian GNU/Linux. Please open an Issue if something is missing. If you use another GNU/Linux distribution, please install the corresponding packages. Even if some packages are available from PyPi stick to the packages provided by the official repository of your GNU/Linux distribution.

  • Runtime dependencies for the CLI

    • python3 (>= 3.9)
    • rsync
    • cron-daemon
    • openssh-client
    • sshfs
    • python3-keyring
    • python3-dbus
    • python3-packaging
    • Recommended
      • encfs

  • Runtime dependencies for the GUI

    • x11-utils
    • python3-pyqt6 (not from PyPi via pip)
    • python3-dbus.mainloop.pyqt6 (not available from PyPi via pip)
    • pkexec
    • polkitd
    • qttranslations6-l10n
    • qtwayland6 (if Wayland is used as display server instead of X11)
    • Recommended
      • For SSH key storage one of these packages
        • python3-secretstorage
        • python3-keyring-kwallet
        • python3-gnomekeyring
      • For diff-like comparing files between backup snapshots one of these packages
        • kompare
        • or meld
      • Optional: Default icons
        • The oxygen icons should be offered as optional dependency since they are used as fallback in case of missing icons (mainly app and system-tray icons)

  • Build and testing dependencies

    • All CLI runtime dependencies including the recommended
    • All GUI runtime dependencies including the recommended
    • build-essential
    • gzip
    • gettext
    • python3-pyfakefs (>= 5.7)
    • Optional but recommended:
      • pylint (>= 3.3.0)
      • flake8
      • ruff (>= 0.6.0)
      • codespell
      • reuse (>= 4.0.0)

  • Dependencies to build documentation

    • All runtime, build, testing dependencies including the recommended
    • mkdocs
    • mkdocs-material

Build and install via make system (recommended)

Important

Install Dependencies before you build and install.

Remember that Back In Time does consist of two packages, which must be built and installed separately accordingly.

  • Command line tool

    1. cd common
    2. ./configure && make
    3. Run unit tests via make test
    4. sudo make install

  • Qt GUI

    1. cd qt
    2. ./configure && make
    3. Run unit tests via make test
    4. sudo make install

You can use optional arguments to ./configure for creating a Makefile. See common/configure --help and qt/configure --help for details.

Testing

Important

Remember to manually test Back In Time and not rely solely on the automatic test suite. See section Manual testing about recommendations how to perform such tests.

After building and installing, make can be used to run the test suite. Since Back In Time consists of two components, common and qt, the tests are segregated accordingly.

$ cd common
$ make test

Or

$ cd qt
$ make test

Alternatively use make test-v for a more verbose output. The make system will use pytest as test runner if available otherwise Python's own unittest module.

SSH

Some tests require an available SSH server. Those tests get skipped if no SSH server is available. The goal is to log into the SSH server on your local computer via ssh localhost without using a password:

  • Generate an RSA key pair executing ssh-keygen. Use the default file name and don't use a passphrase for the key.
  • Populate the public key to the server executing ssh-copy-id.
  • Make the ssh instance run.
  • The port 22 (SSH default) should be available.
  • Authorize the key with $ ssh localhost and insert your user accounts password.

To test the connection just execute ssh localhost and you should see an SSH shell without being asked for a password.

For detailed setup instructions see the how to setup openssh for unit tests.

What happens after you opened a Pull Request (PR)?

In short:

  1. The maintenance team will review your PR in days or weeks.
  2. Modifications may be requested, and the PR will eventually be approved.
  3. One of two labels will be added to the PR:

The maintenance team members are promptly notified of your request. One of them will respond within days or weeks. Note that all team members perform their duties voluntarily in their limited spare time. Please read the maintainers' responses carefully, answer their questions, and try to follow their instructions. Do not hesitate to ask for clarification if needed. At least one maintainer will review and ultimately approve your pull request.

Depending on the topic or impact of the PR, the maintainer may decide that an approval from a second maintainer is needed. This may result in additional waiting time. Please remain patient. In such cases, the PR will be labeled PR: Waiting for review.

If no second approval is necessary, the PR is labeled PR: Merge after creative-break and will remain open for minimum of one week. This rule allows all maintainers the chance to review and potentially veto the pull request.

Instructions about translation

Terminology

  • The translators, as native speakers, are the maintainers of the translation in their language and have the final decision. All following points are strong recommendations, but not written in stone. Language maintainers are free to overule them for good reasons.
  • "Directory" or "Folder"? We prefer "Directory". In our opinion, it is a clearly defined technical term and more precise in describing an element in the file system.
  • Translate "Back In Time"? It is the name of the application. That shouldn't be translated at all.
  • Some points of the following General recommendations for developers are also relevant for translators.

General recommendations for developers

The following points are about creating translatable source strings.

# Avoid escape characters for string delimiters
problematic = _('Hello \'World\'')
correct = _("Hello 'World'")

# Avoid escape characters like new lines
problematic = _('One\nTwo')`
correct = _('One') + '\n' + _('Two')  # <- Separation into multiple strings is
                                      #    no problem, because the translator
                                      #    will have a screenshot.

# Provide meaningful placeholder names
problematic = _('Can not delete {var}.')
correct = _('Can not delete {snapshot_path}.')

# Avoid addressing the person with "you"
problematic = _('Do you really want to delete this snapshot?')
correct = _('Is it really intended to delete this snapshot?')

Consider Right-to-Left (RTL) and Bidirectional (BIDI) languages

In short: Always include punctuation marks (e.g. colons) in the strings to translate.

Languages such as Arabic or Hebrew are read from right to left (RTL). To be more precise, they can have mixed reading directions (BIDI). The GUI library used by Back In Time takes this into account when arrange elements in a window. For example, a text-input widget is left from a label widget. This switched order is the reason why punctuation marks (e.g. colons) in the string of a label widget need to change their direction as well. This task can only be performed by the translator themselves, which is why punctuation marks need to be included in the string to translate.

Be aware of shortcut indicators and possible duplicates

In short:

  1. Use the character & to indicate the letter to access a GUI element via keyboard shortcut.
  2. Be careful not to create conflicts by using the same letter multiple times in the same GUI context.

The Back In Time GUI can be controlled via keyboard shortcuts. In the English version, for example, the menu Back In Time in the main window can be unfolded via Alt+T, Backup via Alt+B, or Help via Alt+H. The keyboard letters to use are indicated in the GUI with an underlined letter. The original string in the source code uses the character & in front of a letter to indicate the shortcut and produce this underline. The example above use the source strings Back In &Time, &Backup, and &Help. This illustrates why it is not appropriate to always use the first letter for shortcuts. Here in this example, &Back In Time and &Backup would use the same letter.

Translating &Backup and &Help into Turkish becomes &Yedek and Y&ardım, where using the first letter only would produce conflicts again.

That is why the translator needs to decide which letter to use.

Treat other translators work with respect

Sometimes it is a matter of taste or habit how do you translate something. People are different, therefore their translation are also different. When modifying an existing translation please consider Comments and History section of that string on our translation platform. There might be another translator who has good reason for this translation. Don't waste other people work for no good reason. Also use the Comments to document your own reasons if you expect discussions or conflicts.

The translation for some specific languages (e.g. German) do have rules every translator should follow. That rules can be found in a colored box on top of the translation platform. Open an issue if you think they should be modified.

Strategy Outline

This is a broad overview of the tasks or steps to enhance Back In Time as a software and as a project. The schedule is not fixed, nor is the order of priority.

Analyzing code and behavior

As none of the current team members were involved in the original development of Back In Time, there is a lack of deep understanding of certain aspects of the codebase and its functionality. Part of the work done in this project involves conducting research on the code, its features, infrastructure, and documenting the findings.

Code quality & unit tests

One challenge resembles a chicken-and-egg problem: the code structure lacks sufficient isolation, making it difficult, if not nearly impossible in some cases, to write valuable unit tests. Heavy refactoring of the code is necessary, but this carries a high risk of introducing new bugs. To mitigate this risk, unit tests are essential to catch any potential bugs or unintended changes in the behavior of Back In Time. Each of the problems is blocking the solution to the other problem.

Considering the three major types of tests (unit, integration, system), the current test suite primarily consists of system tests. While these system tests are valuable, their purpose differs from that of unit tests. Due to the lack of unit tests in the test suite, the codebase has notably low test coverage (see Issue #1489).

The codebase does not adhere to PEP8, which serves as the minimum Python coding style. Utilizing linters in their default configuration is currently not feasible. One of our objectives is to align with PEP8 standards and meet the requirements of code linters. See Issue #1755 about it.

Issues

All existing issues have been triaged by the current team. Labels are assigned to indicate priority, along with a milestone indicating which planned release will address the issue. Some of these issues persists for a long time and involve multiple complex problems. They can be challenging to diagnose due to various factors. Enhancing test coverage and code quality is one aspect aimed at finding and implementing solutions for these issues.

Replace and remove encryption library EncFS

Currently, Back In Time uses EncFS for encrypting backups, but it has known security vulnerabilities (see issue #1549). This requires to remove it. A potential candidate for replacement is GoCryptFS. However, lack of resources hinders this effort. If no volunteers step forward, the encryption feature will be removed, prioritizing user security and team maintenance efforts. See Issue #1734 about the transition process and the discussion about alternatives to EncFS.

Project infrastructure

At present, Back In Time utilizes a build system that relies on make. However, this approach has several shortcomings and does not adhere to modern standards in Python packaging (PEP 621, PEP 517, src layout, pyproject.toml). The team intends to migrate to these contemporary standards to streamline the maintenance of Back In Time (#1575).

Graphical User Interface (GUI): Redesign and Refactoring

Over the years, the GUI has become increasingly complex. It requires a visual redesign as well as code refactoring. Additionally, it lacks tests.

Terminal User Interface (TUI)

Various people use Back In Time via the terminal, for example, through an SSH shell on a headless server. There is an idea of creating a terminal user interface (TUI) or to enhance the existing command-line interface (CLI) (#254) or to create a web-frontend (#209). The later idea was rejected. The TUI idea also has been postponed for now. As an alternative, it is currently being considered to change the format of the configuration file to TOML (#1984), assuming that a TUI, while convenient and pleasant, would no longer be necessary.

Licensing of contributed material

Keep in mind as you contribute, that code, docs and other material submitted to the project are considered licensed under the same terms as the rest of the work. With a few exceptions, this is GNU General Public License Version 2 or later (GPL-2.0-or-later). This project uses SPDX metadata to provide detailed license and copyright information. This data is also machine-readable with REUSE tools.

January 2025