Skip to content

Latest commit

 

History

History
377 lines (303 loc) · 16.4 KB

CONTRIBUTING.md

File metadata and controls

377 lines (303 loc) · 16.4 KB
Raw

How to contribute to Back In Time

😊 Thanks for taking the time to contribute!

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.

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 [email protected]:YOURNAME/backintime.git
$ cd backintime

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

    $ git checkout --branch 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 on 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

Please take the following best practices into account if possible. This will reduce the work load of the maintainers and to increase the chance that your pull request is accepted.

  • Follow PEP 8 as a minimal Style Guide for Python Code.
  • 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").
  • 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 Ubuntu. 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)
    • policykit-1
    • 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 runtime dependencies for CLI and GUI 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. They get skipped if this is not the case. 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.

Strategy Outline

The following tries to give 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 encryption library EncFS or remove it

Currently, Back In Time uses EncFS for encrypting backups, but it has known security vulnerabilities (see issue #1549). This requires replacing it, with GoCryptFS as a potential candidate. 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.

Besides replacing EncFS there is also a discussion going on if Back In Time needs an encryption feature or if encryption should be done on file systems level via LUKS or similar solutions.

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

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). See #254. The proposal of having a web frontend was rejected (#209). Separate projects offering a web fronted will be supported of course.

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.

November 2024