Rdiff-backup is licensed with GNU General Public License v2.0 or later. By contributing to this repository you agree that your work is licensed using the chosen project license.

If something is of interest for the changelog, prefix the statement in the commit body with a three uppercase letters and a colon:

If the commit addresses a specific issue, end the statement with a , closes #NNN message, NNN being of course the number of the issue.

Multiple entries might be required for one single change, e.g. NEW if you introduce a new feature, and CHG because this new features introduces some breaking changes on which the user needs to take actions at upgrade time. You don’t need to notice that you’ve added documentation with DOC for a new feature, this is obvious and redundant; DOC should be reserved for solely documentation changes.

In summary, any commit message could look as follows:

The master branch is always kept in a clean state. Anybody can at any time clone this repository and branch off from master and expect test suite to pass and the code and other contents to be of good quality and a reasonable foundation for them to continue development on.

Each PR focuses on some topic and resist changing anything else. Keeping the scope clear also makes it easier to review the pull request. A good pull request has only one or a few commits, with each commit having a good commit subject and if needed also a body that explains the change.

Each pull request has only one author, but anybody can give feedback. The original author should be given time to address the feedback — reviewers should not do the fixes for the author, but instead let the author keep the authorship. Things can always be iterated and extended in future commits once the PR has been merged, or even in parallel if the changes are in different files or at least on different lines and do not cause merge conflicts if worked on.

It is the responsibility of the PR author to keep it without conflict with master (e.g. if not quickly merged) and overall to support the review process.

Ideally each pull request gets some feedback within 24 hours from it having been filed, and is merged within days or a couple of weeks. Each author should facilitate quick reviews and merges by making clean and neat commits and pull requests that are quick to review and do not spiral out in long discussions.

In versioning we utilize git tags as understood by setuptools_scm. Version strings follow the PEP-440 standard.

The rules are currently as follows (check the files in .github/workflows for details):

The same pre-requisites as for the installation of rdiff-backup also apply for building:

Further python dependencies are documented in requirements.txt.

Additionally following pre-requisites are needed:

All of those should come packaged with your system or available from https://pypi.org/ but if you need them otherwise, here are some sources:

The project has a Makefile that defines steps like all, build, test and others. You can view the contents to see what it exactly does. Using the Makefile is the easiest way to quickly build and test the source code.

By default the Makefile runs all of it’s command in a clean Docker container, thus making sure all the build dependencies are correctly defined and also protecting the host system from having to install them.

The CI pipeline also uses the Makefile, so if all commands in the Makefile succeed locally, the CI is most likely to pass as well.

To install, simply run:

The build process can be also be run separately using pyproject-build.

The setup.py script expects to find librsync headers and libraries in the default location, usually /usr/include and /usr/lib. If you want the setup script to check different locations, use the LIBRSYNC_DIR environment variable. For instance to instruct the setup program to look in /usr/local/include and /usr/local/lib for the librsync files run:

Finally, the LFLAGS and LIBS environment variables are also recognized.

To build from source on Windows, check the Windows tools to build a single executable file which contains Python, librsync, and all required modules.

There are the occasions where you don’t want to make your system "dirty" with an early or even development version of rdiff-backup. This is what virtual environments (or short virtualenv, or even venv) are meant for. Here a very short summary on how to create a virtualenv in the directory …​/rdb (name and exact location aren’t important, but once created, a virtualenv can’t be moved):

The different ways of installing rdiff-backup in such a virtualenv depend on the version type:

At the time of writing these notes, there was an issue where calling the program generates a Segmentation fault (core dumped). This chapter is based on this experience debugging under Fedora 29 (then partially tested again under Fedora 39).

References:

At this stage coredumpctl list shows that coredump is the last one, so that one can call coredumpctl gdb, which itself tells (in multiple steps) that we missing some more debug information, hence the above debuginfo-install statements.

So now back into coredumpctl gdb, with some commands:

<1>get a backtrace of all function calls leading to the coredump (also bt) <2>backtrace with local vars <3>py-bt is the Python version of backtrace <4>jump between frames as listed by bt using their #FrameNumber <5>print some variable/expression in the context of the selected frame

Jumping between frames and printing the different variables, we can recognize that:

At this stage, it seems that the core file has given most of its secrets and we need to debug the live program:

The debugger runs until the breakpoint is reached, after which a succession of next and print <SomeVar> allows me to analyze the code step by step, and to come to the conclusion that cfile = fdopen(python_fd, ... is somehow wrong as it creates a null file pointer whereas python_fd looks like a valid file descriptor (an integer equal to 5).

If you get something looking like a ResourceWarning: Enable tracemalloc to get the object allocation traceback

This tells you indeed where the file was opened: Object allocated at (most recent call last) but it still requires deeper analysis to understand the reason.

In order to make sure the debug messages are properly sorted, you need to have the verbosity level 9 set-up, mix stdout and stderr, and then use the date/time output to properly sort the lines coming both from server and client, while making sure that lines belonging together stay together. The result command line might look as follows:

Since version 2.1+, you can use the server’s --debug option to debug remotely the server process. Make sure first that you’ve installed rpdb (remote pdb) and netcat (also called nc or ncat).

If you make sure that you run the latest code version, and set all the environment variables correctly, you can then connect remotely to the spawned server process:

Once you’ve done this, in another terminal, you can call netcat localhost 4445 (resp. ncat or nc, and 4444 by default) and you’ll arrive on the pdb command line. You’re one or two n(ext) steps away from the pre-check method, so you can start to debug the server process relatively early (not the argument parsing step though).

When debugging, the fact that rdiff-backup uses a lot of iterators makes it rather complex to understand what’s happening. It would sometimes make it easier to have a list to study at once of iterating painfully through each but if you simply use p list(some_iter_var), you basically run through the iterator and it’s lost for the program, which can only fail.

The solution is to use itertools.tee, create a copy of the iterator and print the copy, e.g.:

Assuming the iteration has no side effects, the initial variable inc_pair_iter is still valid for the rest of the program, whereas the mycopy is "dried out" (but you can repeat the tee operation as often as you want).

Depending on the kind of issue, there are some good places to put a breakpoint:

If you need to check the details of the coverage report after the run of tox -e pyXY, you can simply call something like the following:

The report output will show you which code lines aren’t covered by the tests.

Because there is one draft release created for each pipeline job, it can be quite a lot when one tests the release pipeline. The GitHub WebUI requires quite a lot of clicks to delete them. A way to simplify (a bit) the deletion is to install the command line tool hub and call the following command:

the 2 compared to $3 is the number of days, so that you get one tab opened in firefox for each draft release, so that you only need 2 clicks and one Ctrl+W (close the tab) to delete those releases.