Developer Documentation: Difference between revisions

From Proxmox VE
Jump to navigation Jump to search
 
(45 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Introduction ==
== Introduction ==
This wiki describes the higher level developer documentation for all Proxmox projects, including Proxmox VE, Proxmox Backup Server and Proxmox Mail Gateway and Proxmox Offline Mirror.


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.
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/addition).
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 ==
== 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 development additional features, this is the place to start.
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.
 
Proxmox VE Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
 
Archive: https://lists.proxmox.com/pipermail/pve-devel/


PVE Development List: https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
=== Public Inbox ===
In addition to the native mailing list archive, Proxmox runs a Public Inbox instance at [https://lore.proxmox.com lore.proxmox.com] that archives and indexes all messages sent to all of our public mailing lists (<code>pve-devel</code>, <code>pbs-devel</code>, <code>pmg-devel</code>, <code>pve-user</code>).


Archive: https://pve.proxmox.com/pipermail/pve-devel/
Public Inbox also provides a convenient and powerful search interface, see the [https://lore.proxmox.com/pve-devel/_/text/help/ public-inbox help] for an overview and the [https://public-inbox.org/README.html official Public Inbox README] for more features. There are also tools that build on top of Public Inbox's features, such as [https://b4.docs.kernel.org/en/latest/ b4], which can help to pull and review patches.


== Access to Code Repository (git) ==
== Access to Code Repository (git) ==
Line 17: Line 24:
== Build instructions ==
== Build instructions ==


You could find build instruction here :
You could find build instructions here :


https://git.proxmox.com/?p=pve-common.git;a=blob_plain;f=README.dev;hb=HEAD
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 <code>/etc/apt/sources.list</code> file:
=== For Proxmox VE 8.x based on Debian 12 Bookworm ===
  deb http://download.proxmox.com/debian/devel/ bookworm main
=== For Proxmox VE 7.x based on Debian 11 Bullseye ===
  deb http://download.proxmox.com/debian/devel/ bullseye main
=== For Proxmox VE 6.x based on Debian 10 Buster ===
  deb http://download.proxmox.com/debian/devel/ buster main


== Checking out a git repository ==
== Checking out a git repository ==


To clone a repository run 'git clone' with the repository name prefixed with the common URL: <nowiki>git://git.proxmox.com/git/</nowiki>
To clone a repository run 'git clone' with the repository name prefixed with the common URL: <nowiki>git://git.proxmox.com/git/</nowiki>
<source lang="bash">
# git clone git://git.proxmox.com/git/pve-manager.git
# git clone git://git.proxmox.com/git/pve-manager.git
 
</source>
To update an already cloned project to the current version use:
To update an already cloned project to the current version use:
<source lang="bash">
# git pull
# git pull
</source>


== Working on the code ==
== Working on the code ==
=== Coding guidelines ===
=== Coding guidelines ===
The codebase mostly contains perl code, with javascript for the user interface, and C for the Proxmox Cluster Filesystem.
The codebase mostly contains Perl and rust code for the backend, JavaScript for the user interface, and C for the Proxmox Cluster Filesystem and upstream projects like the Linux kernel or QEMU.
For Perl we recommend to have a look at our [[Perl Style Guide|perl style guide]].
The documentation for Proxmox VE is written in AsciiDoc, using the python implementation.
For Javascript we use jslint to check code standards, so before submitting a patch you should call
 
==== Perl ====
For Perl, we recommend having a look at our [[Perl Style Guide|'''perl style guide''']].
 
==== Rust ====
For our Rust code we use <code>rustfmt</code> (e.g., through <code>cargo fmt</code>) with default settings.
 
Compiler warnings must be avoided.
Additionally, one might check lints reported by <code>cargo clippy</code>, but we do not accept mass fixing of those all over the place, such fixes are not always productive and can introduce actual subtle (logical) errors.


<source lang="bash">
==== JavaScript ====
make lint
For JavaScript, we use <code>eslint</code> as separate package to check basic code standards. New contribution must not ensure that eslint doesn't output any warning or error.
</source>
Check out [[Javascript Style Guide]]


in the <tt>www/manager6</tt> directory of your copy of the pve-manager repository.
We use the ExtJS framework for the web UI Components, its API documentation can be found at https://docs.sencha.com/extjs/7.0.0/.
https://pve.proxmox.com/wiki/Proxmox_VE_API
 
We use the ExtJS framework for the Gui Components, its API documentation can be found [http://docs.sencha.com/extjs/6.0.1/index.html here.]
==== Documentation ====
 
Avoid overly long line. Use line-length from context, which is 80 character columns most of the time, try to stay below 100 as maximum.
 
Adhere to our [[Technical Writing Style Guide]].


=== Using git ===
=== Using git ===
Line 54: Line 89:
First, configure your ''real'' name and email address for git, if not done already:
First, configure your ''real'' name and email address for git, if not done already:


<source lang="bash">
$ git config --global user.name "John Doe"
$ git config --global user.name "John Doe"
$ git config --global user.email john@example.com
$ git config --global user.email john@example.com
</source>


This will be used to sign off commits as your work.
This will be used to sign off commits as your work.
Line 63: Line 96:
It is recommended to start a feature branch before working on the code locally:
It is recommended to start a feature branch before working on the code locally:


<source lang="bash">
# git checkout -f -b my_branch master
# git checkout -f -b my_branch master
</source>


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
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
<source lang="bash">
# git diff master..my_branch
# git diff master..my_branch
 
</source>
==== Commits and Commit Messages ====
 
Then, make your commit (try to make small, but self-contained, commits) and include a sign-off line (-s).
 
In general, commit messages should be written with the following style guide in mind:
 
* Write your commit message in the imperative: "Fix bug" and <u>not</u> "Fixed bug" or "Fixes bug."
*:  This convention matches up with commit messages generated by commands like git merge and git revert.
* Avoid using "we", as for readers it's unclear who is meant.
* Make sure the '''line-length''' (text-width, column count) of the commit's message is '''not longer than 72 characters'''.
: Note, HTTPS links and git trailers (e.g., <code>Signed-off-by:</code>, <code>Reviewed-by:</code> or <code>Fixes:</code>) are an exception and must '''not''' be split over multiple lines.
* Add your <code>Signed-off-by: Your Name <your.mail@example.com></code> trailer and also track trailers from other people, like <code>Suggested-by</code>, <code>Co-authored-by</code>, <code>Tested-by</code>, <code>Reviewed-by</code>
: Note: Trailers should be ''[https://en.wikipedia.org/wiki/Causality causally] ordered''. For instance, a <code>Suggested-by</code> should be listed ''before'' a <code>Signed-off-by</code> (the suggestion ''caused'' you to create the commit), a <code>Tested-by</code> ''after'' a <code>Signed-off-by</code> (a commit is created before one is able to test it).
 
* If the commit fixes a bug '''start''' with that information in this form: <code>fix #1234: summary here</code>
*: If it implements a feature tracked on Bugzilla you can also use: <code>close #1234: summary here</code> albeit <code>fix #1234:</code> is more commonly used and also fine
* Try to add a tag prefix to denote the subsystem you're (mainly) changing, if an obvious choice exists.
** For example, if you changed the QEMU UI component in pve-manager, a possible tag could be <code>ui: qemu: rest of summary here</code>
** Don't add tags for things that are already clear from context, for example, adding a <code>qemu</code> tag for a patch in the qemu-server repository has no use.
** But, do '''not''' just paste the affected files, including (parts of the) path and maybe even the file ending, as tag! That has no use (already contained in diff stat) and just makes it harder to read.
* Commit messages are made for humans and thus should focus on a short summary of core semantic changes.
** Ideally, the subject is worded such, that it can be copied directly into the <code>debian/changelog</code>, which is consumed by end users.
** Most of the time it's best to avoid mentioning implementations details, like for example specific function or type names in verbatim as written in the programming language.
*: An exception can be changes, that do not have any visible (semantic) effect for users, like pure refactoring (movement of code without changing its logic) or preparations, especially if they happen in pure library repos/crates. But even there one often benefits from a higher-level human-readable overview too.
 
You can always edit the commit message of the most recent commit using amend:
# git commit --amend
 
If you work on a series you can use the git rebase command to re-order, drop, squash/fixup and edit both the whole commit or just rewording its message:
 
git rebase -i --autosquash --autostash origin/master
 
The <code>autostash</code> is not required, but convenient if there are still pending changes, it will stash before rebase starts and apply again after rebase is done.
The <code>autosquash</code> is also not required, but very convenient to auto squash fixups (<code>git commit --fixup=<ref></code>) made for older commits in a development series


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: <tt>Fix #1234: summary here</tt>
* If it implements a feature tracked on bugzilla use: <tt>Close #1234: summary here</tt>
* 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:
The following command will take all changes of tracked files and add it to the commit:
# git commit -s -a


<source lang="bash">
New files won't get added automatically. To do that, or to just add some changed files to a commit, use
# git commit -s -a
# git add newfile1.pl file2.pl
</source>
 
New files won't get added automatically. To do that, or just add some of the changed files to a commit, use
<source lang="bash">
# git add newfile1.pl file2.pl
</source>


You can always look at what will get into commit with:
You can always look at what will get into commit with:
<source lang="bash">
# git diff --staged
# git diff --staged
</source>


== Preparing Patches ==
== Preparing Patches ==


{{note| Note that we need a valid [[#Software License and Copyright|CLA]] to include your changes|reminder}}
{{note| For all repositories where Proxmox is the upstream, and where not explicitly noted otherwise, a valid [[#Software License and Copyright|CLA]] is required to include your changes|reminder}}


Since we have several projects in our git repository and only one development
Since we have several projects in our git repository and only one development
Line 103: Line 155:
you shorten them (eg. remove the 'pve-' prefix).
you shorten them (eg. remove the 'pve-' prefix).


Creating the raw patch series, for instance for the <tt>pve-container</tt>
Creating the raw patch series, for instance for the <tt>pve-container</tt> package:
package:
# rm -rf my-patches/      # to clean left-overs
<source lang="bash">
# git format-patch -o my-patches/ --subject-prefix="PATCH container" master..my_branch --cover-letter
# rm -rf my-patches/      # to clean left-overs
# git format-patch -o my-patches/ --subject-prefix="PATCH container" master..my_branch --cover-letter
</source>


Explain in the cover letter the aim of your patches:
Explain in the cover letter the aim of your patches:
<source lang="bash">
edit my-patches/0000-cover-letter.patch
edit my-patches/0000-cover-letter.patch
</source>


Sending patches:
Sending patches:
<source lang="bash">
# git send-email --to=pve-devel@lists.proxmox.com  my-patches/00*.patch
# git send-email --to=pve-devel@pve.proxmox.com  my-patches/00*.patch
# rm -rf my-patches/      # to clean left-overs
# rm -rf my-patches/      # to clean left-overs
</source>


If you wish to write comments for individual patches, you can do that either in
If you wish to write comments for individual patches, you can do that either in
the cover-leter, or in the patch's ''commit summary section'' (between the line
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
consisting of 3 consecutive dashes ending your commit message and before the
list of files with their change-counts.
list of files with their change-counts.
Line 129: Line 174:
<pre>
<pre>
From 12345abcde Mon Sep 12 00:00:00 2001
From 12345abcde Mon Sep 12 00:00:00 2001
From: Git Commiter <some email address>
From: Git Committer <some email address>
Date: Fri, 7 Oct 2016 08:30:17 +0200
Date: Fri, 7 Oct 2016 08:30:17 +0200
Subject: [PATCH container 1/2] Fix #1013: this and that
Subject: [PATCH v2 container 1/2] Fix #1013: this and that


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


Signed-off-by: Firstname Lastname <firstname@lastname.email>
Signed-off-by: Firstname Lastname <firstname@lastname.email>
---
---
  ***HERE*** you can write your comments.
  ***HERE*** you can write your comments.
  If this is a new version of an old patch, explain your changes here
  If this is a new version of an old patch, explain your changes here,
 
for example:
changes since v1:
* fixed an error in the new regex
* reworked algorithm to be O(n)
  src/PVE/Tools.pm | 2 +-
  src/PVE/Tools.pm | 2 +-


Line 146: Line 197:
(...)
(...)
</pre>
</pre>
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 ===
=== Versioned Patches ===


If an updated versioned of your patch series is called for, it should be sent
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.
as a new series rather than as reply to the old series. (For trivial/short
Always send the whole series with all patches showing the same version.
single patches either way is fine.) Please mark your versions in your subject
prefix with a smal 'v' followed by the version number like this:


<source lang="bash">
Please mark your versions in your subject prefix with a small 'v' followed by the version number, git can do this for you using the <code>-vX</code> command line option. For example:
# git format-patch -o my-patches/ --subject-prefix="PATCH v2 container" master..my_branch
</source>


Please list all the changes to the previous versions in the ''commit summary
# git format-patch -o my-patches/ --subject-prefix="PATCH container" -v2 master..my_branch
 
Please '''list all the changes to the previous versions''' in the ''commit summary
section'' as shown in the above example.
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, like <code>no changes since last version</code>


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


=== Reviewing patches ===
=== Reviewing patches ===
After reviewing patches which affect a subsystem you maintain, you can notify
After reviewing patches which affect a subsystem you maintain, you can notify  
with
committers that you reviewed the patch and are OK with the changes by using:
<pre>
Acked-by: Full Name <email address>
Acked-by: name / email address
</pre>
 
committers that you reviewed the patch and are OK with the changes.


=== Convenience Settings ===
=== Convenience Settings ===


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


<source lang="bash">
$ git config --local sendemail.to pve-devel@lists.proxmox.com
$ git config --local sendemail.to pve-devel@pve.proxmox.com
$ git config --local format.subjectprefix 'PATCH container'
$ git config --local format.subjectprefix 'PATCH container'
$ git config --local format.signoff true  
$ git config --local format.signoff true  
</source>


Now the commands to create and send patches become:
Now the commands to create and send patches become:
<source lang="bash">
# git format-patch -o my-patches/ master..my_branch
# git format-patch -o my-patches/ master..my_branch
# git send-email --compose my-patches/00*.patch
# git send-email --compose my-patches/00*.patch
 
</source>
== Sending Patches ==
 
Always use <code>git send-email</code> 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 to setup <code>git send-email</code>.
 
=== Using Authenticated SMTP Server ===
 
<code>git send-email</code> 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 <code>~/.gitconfig</code> or to the per project <code>.git/config</code>.
<code>git send-email</code> will then use these settings by default and ask you for the password on sending.
 
=== Example ===
 
To send the last two commits for a Proxmox VE project to the Proxmox VE development list you could then execute:
 
  git send-email --to="pve-devel@lists.proxmox.com" -2
 
If you're not used to <code>git send-email</code> it can be a good test to first send the patches to an email address of yourself, that allows to ensure all details and commands are correct.


== Bugtracker (bugzilla) ==
== Bugtracker (bugzilla) ==
Line 193: Line 277:


== Software License and Copyright ==
== 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.
We only include code licensed under the respective repo's license, visible under <code>debian/copyright</code>. For most of our projects, or if in doubt, this is the 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.
Additionally, we require that contributors send us a contributor license agreement form by email to <code>office@proxmox.com</code>.
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 [http://www.harmonyagreements.org 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.
With the contributor agreement chosen by Proxmox, the [http://www.harmonyagreements.org 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:
We've tried to keep the agreement as simple and comprehensible as possible. It comes in two flavors:
Line 208: Line 294:
* [https://git-scm.com/documentation Git Documentation]
* [https://git-scm.com/documentation Git Documentation]
* [[Perl Style Guide|Our Perl Style Guide]]
* [[Perl Style Guide|Our Perl Style Guide]]
* [[Javascript Style Guide|Our JavaScript Style Guide]]


[[Category: HOWTO]]
[[Category: HOWTO]]
[[Category:Development]]

Latest revision as of 08:28, 16 October 2024

Introduction

This wiki describes the higher level developer documentation for all Proxmox projects, including Proxmox VE, Proxmox Backup Server and Proxmox Mail Gateway and Proxmox Offline Mirror.

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.

Proxmox VE Development List: https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

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

Public Inbox

In addition to the native mailing list archive, Proxmox runs a Public Inbox instance at lore.proxmox.com that archives and indexes all messages sent to all of our public mailing lists (pve-devel, pbs-devel, pmg-devel, pve-user).

Public Inbox also provides a convenient and powerful search interface, see the public-inbox help for an overview and the official Public Inbox README for more features. There are also tools that build on top of Public Inbox's features, such as b4, which can help to pull and review patches.

Access to Code Repository (git)

https://git.proxmox.com

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:

For Proxmox VE 8.x based on Debian 12 Bookworm

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

For Proxmox VE 7.x based on Debian 11 Bullseye

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

For Proxmox VE 6.x based on Debian 10 Buster

 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 and rust code for the backend, JavaScript for the user interface, and C for the Proxmox Cluster Filesystem and upstream projects like the Linux kernel or QEMU. The documentation for Proxmox VE is written in AsciiDoc, using the python implementation.

Perl

For Perl, we recommend having a look at our perl style guide.

Rust

For our Rust code we use rustfmt (e.g., through cargo fmt) with default settings.

Compiler warnings must be avoided. Additionally, one might check lints reported by cargo clippy, but we do not accept mass fixing of those all over the place, such fixes are not always productive and can introduce actual subtle (logical) errors.

JavaScript

For JavaScript, we use eslint as separate package to check basic code standards. New contribution must not ensure that eslint doesn't output any warning or error. Check out Javascript Style Guide

We use the ExtJS framework for the web UI Components, its API documentation can be found at https://docs.sencha.com/extjs/7.0.0/.

Documentation

Avoid overly long line. Use line-length from context, which is 80 character columns most of the time, try to stay below 100 as maximum.

Adhere to our Technical Writing Style Guide.

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

Commits and Commit Messages

Then, make your commit (try to make small, but self-contained, commits) and include a sign-off line (-s).

In general, commit messages should be written with the following style guide in mind:

  • Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug."
    This convention matches up with commit messages generated by commands like git merge and git revert.
  • Avoid using "we", as for readers it's unclear who is meant.
  • Make sure the line-length (text-width, column count) of the commit's message is not longer than 72 characters.
Note, HTTPS links and git trailers (e.g., Signed-off-by:, Reviewed-by: or Fixes:) are an exception and must not be split over multiple lines.
  • Add your Signed-off-by: Your Name <your.mail@example.com> trailer and also track trailers from other people, like Suggested-by, Co-authored-by, Tested-by, Reviewed-by
Note: Trailers should be causally ordered. For instance, a Suggested-by should be listed before a Signed-off-by (the suggestion caused you to create the commit), a Tested-by after a Signed-off-by (a commit is created before one is able to test it).
  • If the commit fixes a bug start with that information in this form: fix #1234: summary here
    If it implements a feature tracked on Bugzilla you can also use: close #1234: summary here albeit fix #1234: is more commonly used and also fine
  • Try to add a tag prefix to denote the subsystem you're (mainly) changing, if an obvious choice exists.
    • For example, if you changed the QEMU UI component in pve-manager, a possible tag could be ui: qemu: rest of summary here
    • Don't add tags for things that are already clear from context, for example, adding a qemu tag for a patch in the qemu-server repository has no use.
    • But, do not just paste the affected files, including (parts of the) path and maybe even the file ending, as tag! That has no use (already contained in diff stat) and just makes it harder to read.
  • Commit messages are made for humans and thus should focus on a short summary of core semantic changes.
    • Ideally, the subject is worded such, that it can be copied directly into the debian/changelog, which is consumed by end users.
    • Most of the time it's best to avoid mentioning implementations details, like for example specific function or type names in verbatim as written in the programming language.
    An exception can be changes, that do not have any visible (semantic) effect for users, like pure refactoring (movement of code without changing its logic) or preparations, especially if they happen in pure library repos/crates. But even there one often benefits from a higher-level human-readable overview too.

You can always edit the commit message of the most recent commit using amend:

# git commit --amend

If you work on a series you can use the git rebase command to re-order, drop, squash/fixup and edit both the whole commit or just rewording its message:

git rebase -i --autosquash --autostash origin/master

The autostash is not required, but convenient if there are still pending changes, it will stash before rebase starts and apply again after rebase is done. The autosquash is also not required, but very convenient to auto squash fixups (git commit --fixup=<ref>) made for older commits in a development series


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 to just add some 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

Yellowpin.svg Note: For all repositories where Proxmox is the upstream, and where not explicitly noted otherwise, a valid CLA is required 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 v2 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,
 for example:
 
 changes since v1:
 * fixed an error in the new regex
 * reworked algorithm to be O(n)
 
 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, git can do this for you using the -vX command line option. For example:

# git format-patch -o my-patches/ --subject-prefix="PATCH container" -v2 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, like no changes since last version

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 committers that you reviewed the patch and are OK with the changes by using:

Acked-by: Full Name <email address>

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 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 to setup 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 for the password on sending.

Example

To send the last two commits for a Proxmox VE project to the Proxmox VE development list you could then execute:

 git send-email --to="pve-devel@lists.proxmox.com" -2

If you're not used to git send-email it can be a good test to first send the patches to an email address of yourself, that allows to ensure all details and commands are correct.

Bugtracker (bugzilla)

https://bugzilla.proxmox.com

Software License and Copyright

We only include code licensed under the respective repo's license, visible under debian/copyright. For most of our projects, or if in doubt, this is the GNU Affero General Public License, version 3 http://www.gnu.org/licenses/agpl-3.0.html.

Additionally, we require that contributors send us a contributor license agreement form by email to office@proxmox.com. 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:

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.

See Also