Developer Documentation

Introduction

Please communicate you plans with us, before starting any development. It is important to have a common view of the problem and corresponding solution, in order to avoid duplicated work and unnecessary efforts.

Our source code repository is read-only. To contribute code, send it as a patch (git diff) to the pbs-devel mailing list. We will review your patch and apply it (and possible corrections/additions) if the review is successful. Note that we will only include code that meets our quality criteria.

Mailing List

This is the primary communication channel for developers to discuss new features and implementation details. If you are a developer and you want to develop additional features, this is the place to start.

PBS Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel

Archive: https://lists.proxmox.com/pipermail/pbs-devel/

Access to Code Repository (git)

You can find all of our project repositories at the link below. The repositories relating to Proxmox Backup are under the section titled "rust".

https://git.proxmox.com

Build instructions

You can find build instructions here:

https://git.proxmox.com/?p=proxmox-backup.git;a=blob_plain;f=README.rst;hb=HEAD

Development Package Repository

Some packages required for development can only be found in the devel repository. This is a cross-project repository and may be used for all Proxmox projects.

Add the following to the /etc/apt/sources.list file:

 deb http://download.proxmox.com/debian/devel/ buster main

Checking out a git repository

To clone a repository, run 'git clone' with the repository name prefixed with the common URL: git://git.proxmox.com/git/

# git clone git://git.proxmox.com/git/proxmox-backup.git

To update an already cloned project to the current version use:

# git pull

Working on the code

Coding guidelines

The codebase is mostly Rust, with JavaScript for the web-interface.

We use the ExtJS framework for the GUI components; its API documentation can be found here.

Using git

If you are not familiar with git, it's worth having a look at this interactive tutorial: https://try.github.io, and reading the brief introduction chapter from the official git documentation: https://git-scm.com/docs/gittutorial to gain basic knowledge on it.

First, configure your real name and email address for git, if not done already:

$ git config --global user.name "John Doe"
$ git config --global user.email john@example.com

This will be used to sign off commits as your work.

We recommend that you start a feature branch before working on the code locally:

# git checkout -b my_branch master

After this, you can start working on your improvements. You can compare your changes to the current PBS master branch easily with:

# git diff master..my_branch

Commits and Commit Messages

After making changes, commit them (try to make small, self-contained commits) and include a sign-off line (-s).

• Make sure the line length of the commit's message is not longer than 70 characters. HTTPS links are an exception and should not be split.
• If it fixes a bug, start with that information, in the form: fix #1234: summary here
• If it implements a feature tracked on Bugzilla, use: close #1234: summary here, albeit fix #1234: is commonly used and also fine.
• Add a tag to the beginning, if an obvious choice exists. For example, if you made a change to the datastore API, a possible tag could be api: datastore: summary here

However, do not just paste the changed file, including path and file ending as a tag. This has no use and makes it harder to read.

The following command will take all the changes in tracked files and commit them:

# git commit -s -a

New files won't get added automatically with this command. To stage new or changed files for a commit, use:

# git add newfile1.rs file2.rs

You can always look at what will be committed with:

# git diff --staged

Preparing Patches

Note: We need a valid CLA to include your changes

Since we have several projects in our git repository that use the pbs-devel mailing list, we ask you to clarify which repository your patches are meant for, by specifying it in the subject prefix, for example, 'proxmox' or 'proxmox-backup'.

Example: Creating the raw patch series for the proxmox-backup package:

# rm -rf my-patches/       # to clean left-overs
# git format-patch -o my-patches/ --subject-prefix="PATCH proxmox-backup" master..my_branch --cover-letter

Explain in the cover letter the aim of your patches:

edit my-patches/0000-cover-letter.patch

Sending patches:

# git send-email --to=pbs-devel@lists.proxmox.com  my-patches/00*.patch
# rm -rf my-patches/       # to clean left-overs

If you wish to write comments for individual patches, you can do that either in the cover-letter, or in the patch's commit summary section (between the line consisting of 3 consecutive dashes ending your commit message and before the list of files with their change-counts).

Example:

From 12345abcde Mon Sep 12 00:00:00 2001
From: Git Committer <some email address>
Date: Fri, 7 Oct 2020 08:30:17 +0200
Subject: [PATCH proxmox-backup 1/2] Fix #1013: this and that

Here is your commit message.
It explains the bugfix and ends after this line.

Signed-off-by: Firstname Lastname <firstname@lastname.email>
---
 ***HERE*** you can write your comments.
 If this is a new version of an old patch, explain your changes here

 src/backup.rs | 2 +-

diff --git a/src/backup.rs b/src/backup.rs
(...)

If you want to send several related patches that contain changes to different repositories, you can first iterate over all involved repositories, save the patches into one directory and then do a single git send-email over all generated patches. For example, lets go to a few repos and format the most recent commit as a patch to /tmp/patchq, then send it:

# cd proxmox-backup; git format-patch -s -o /tmp/patchq -1 
# cd ../proxmox; git format-patch -s -o /tmp/patchq -1  
# git send-email --compose --to=pbs-devel@lists.proxmox.com /tmp/patchq/*

Using "start-number" and the likes can improve this further, but this is a good start.

Versioned Patches

If an updated version of your patch series is called for, it should be sent as a new series, rather than as a reply to the old series. Always send the entire series, with all patches showing the same version. Please mark your versions in the subject prefix, with a small 'v', followed by the version number, like this:

# git format-patch -o my-patches/ --subject-prefix="PATCH v2 proxmox-backup" master..my_branch

Please list all the changes to the previous versions in the commit summary section as shown in the above example. For patches with no changes to the previous version, you should mention that there were no changes in the summary section.

If your series has a cover letter, summarize all changes in it as well.

Reviewing patches

After reviewing patches which affect a subsystem you maintain, you can notify committers that you have reviewed the patch and are OK with the changes, with:

Acked-by: name / email address

Convenience Settings

For convenience, you can store the pbs-devel email address and the repository's default subject prefixes in your repository clones' configurations as follows:

$ git config --local sendemail.to pbs-devel@lists.proxmox.com
$ git config --local format.subjectprefix 'PATCH proxmox-backup'
$ git config --local format.signoff true

Now the commands to create and send patches become:

# git format-patch -o my-patches/ master..my_branch
# git send-email --compose my-patches/00*.patch

Sending Patches

Always use git send-email to send out patches, otherwise the indentation and formatting will get mangled and the patch cannot be applied anymore.

Tutorial

See https://git-send-email.io/ for an interactive tutorial on setting up git send-email.

Using Authenticated SMTP Server

git send-email can be instructed to use a specific SMTP server for sending. The following shows an anonymized config section example:

[sendemail]
        smtpencryption = tls
        smtpserver = webmail.example.com
        smtpserverport = 587
        smtpuser = j.smith@example.com
        smtpsslcertpath =
        confirm = always

Add this to your global user ~/.gitconfig or to the per project .git/config. git send-email will then use these settings by default and ask you once for the password when sending.

Bugtracker (Bugzilla)

We use Bugzilla to track bugs and feature requests for our products.

https://bugzilla.proxmox.com

Software License and Copyright

We only include code licensed under GNU Affero General Public License, version 3 http://www.gnu.org/licenses/agpl-3.0.html.

Additionally, we ask contributors to send us a contributor license agreement form by email. This agreement establishes a relationship between us and the contributor, gives details on what it means when the contributor grants permission for their work to be included in a project, and enables us to better maintain these projects.

With the contributor agreement chosen by Proxmox, the Harmony CLA, the contributor gives Proxmox a license to use their contributions. The contributor continues to own the copyright in the contribution, with full rights to re-use, re-distribute, and continue modifying the contributed code, allowing them to also share that contribution with other projects.

We've tried to keep the agreement as simple and comprehensible as possible. It comes in two flavors:

• one for individual contributors
• and one for entities contributors (companies, foundations, or other organizations).

If you are making a contribution that is not your own work (for example, a patch or library written by someone else), please contact office@proxmox.com for guidance on whether any additional steps are needed.

See Also

• Git Documentation