Developer Documentation
Introduction
Please coordinate your efforts with us before starting any development. It is important to have a common view of the problem and the corresponding solution – just to avoid duplicated or unnecessary efforts.
We will only include software which matches our quality criteria. The source code repository is read only. To include some code, send it as patch (git diff) to the pve-devel mailing list. We will review your code and commit after a successful review (and possible corrections/additions).
Mailing List
This is the primary communication channel for developers, discussing new features and implementation details. If you are a developer and you want to develop additional features, this is the place to start.
PVE Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
Archive: https://lists.proxmox.com/pipermail/pve-devel/
Access to Code Repository (git)
Build instructions
You could find build instructions here :
https://git.proxmox.com/?p=pve-common.git;a=blob_plain;f=README.dev;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/pve-manager.git
To update an already cloned project to the current version use:
# git pull
Working on the code
Coding guidelines
The codebase mostly contains perl code, with javascript for the user interface, and C for the Proxmox Cluster Filesystem. For Perl we recommend to have a look at our perl style guide. For Javascript we use jslint to check code standards, so before submitting a patch you should call
make lint
in the www/manager6 directory of your copy of the pve-manager repository. https://pve.proxmox.com/wiki/Proxmox_VE_API 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 could be worth to take a look at this interactive tutorial: https://try.github.io and read a 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.
It is recommended to start a feature branch before working on the code locally:
# git checkout -f -b my_branch master
After this you can start working on your improvements. You'll be able to compare your changes to the current PVE master branch easily with
# git diff master..my_branch
Then, make your commit (try to make small commits) and include a sign-off line (-s).
- Make sure the line length of the commit's message is not longer than 70 characters.
- If it fixes a bug start with that information in this form: Fix #1234: summary here
- If it implements a feature tracked on bugzilla use: Close #1234: summary here
- Try to add a tag at start, if an obvious choice exists. E.g., if you changed the QEMU UI component in pve-manager, a possible tag could be 'ui: qemu: summary here'
The following command will take all changes of tracked files and add it to the commit:
# git commit -s -a
New files won't get added automatically. To do that, or just add some of the changed files to a commit, use
# git add newfile1.pl file2.pl
You can always look at what will get into commit with:
# git diff --staged
Preparing Patches
|
Note: Note that we need a valid CLA to include your changes |
Since we have several projects in our git repository and only one development mailing list, we ask you to clarify which repository your patches are meant for by specifying it in the subject prefix. Since some names are long it's fine if you shorten them (eg. remove the 'pve-' prefix).
Creating the raw patch series, for instance for the pve-container package:
# rm -rf my-patches/ # to clean left-overs
# git format-patch -o my-patches/ --subject-prefix="PATCH container" 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=pve-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 2016 08:30:17 +0200 Subject: [PATCH container 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/PVE/Tools.pm | 2 +- diff --git a/src/PVE/Tools.pm b/src/PVE/Tools.pm (...)
If you want to send several related patches for one feature but 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 patch to /tmp/patchq, then send it:
# cd pve-manager; git format-patch -s -o /tmp/patchq -1
# cd ../pve-guest-common; git format-patch -s -o /tmp/patchq -1
# cd ../pve-docs; git format-patch -s -o /tmp/patchq -1
# git send-email --compose --to=pve-devel@lists.proxmox.com /tmp/patchq/*
Using "start-number" and the like can improve this further, but it's 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 reply to the old series. Always send the whole series with all patches showing the same version. Please mark your versions in your subject prefix with a small 'v' followed by the version number like this:
# git format-patch -o my-patches/ --subject-prefix="PATCH v2 container" 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, also summarize all changes in it as well.
Reviewing patches
After reviewing patches which affect a subsystem you maintain, you can notify with
Acked-by: name / email address
committers that you reviewed the patch and are OK with the changes.
Convenience Settings
For convenience you can store the pve-devel email address and the repository's default subject prefixes in your repository clones' configurations as follows:
$ git config --local sendemail.to pve-devel@lists.proxmox.com
$ git config --local format.subjectprefix 'PATCH container'
$ 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 sent out patches, else the indentation and formatting will get mangled and the patch cannot be applied anymore.
Using Authenticated SMTP Server
Git send mail 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 or to the per project .git/config.
git send-email will then use these settings by default and ask you for the password once on sending.
Bugtracker (bugzilla)
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 be better stewards of 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 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.