Developer Documentation: Difference between revisions

From Proxmox VE
Jump to navigation Jump to search
m (Add a See Also section with a link to the git documentation)
(Detailed git patch guide, added patch versioning workflow)
Line 43: Line 43:
</source>
</source>


Then, make your commit (try to make small commits) :
Then, make your commit (try to make small commits) and include a sign-off line (-s).
* Make sure the first line of the commit is ''not longer than 70 characters''.
* In the rest of the message, limit the line length to 80 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>
<source lang="bash">
<source lang="bash">
# git commit -a
# git commit -s -a
</source>
</source>
When you have finished your modifications, create patches :
 
== Preparing Patches ==
 
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 mant 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 <tt>pve-container</tt>
package:
<source lang="bash">
<source lang="bash">
# git format-patch -o /tmp/ --signoff master..my_branch
# rm -rf my-patches/      # to clean left-overs
# git format-patch -o my-patches/ --subject-prefix="PATCH container" master..my_branch
</source>
</source>
Then send your patchs to pve-devel@pve.proxmox.com (git-email package has to be installed and configured) with a short description in the email body
 
Sending patches:
<source lang="bash">
<source lang="bash">
# git send-email --to=pve-devel@pve.proxmox.com --compose /tmp/00* --subject="What this patch for"
# git send-email --to=pve-devel@pve.proxmox.com --compose my-patches/00*.patch
# rm -rf my-patches/      # to clean left-overs
</source>
</source>


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
consisting of 3 consecutive dashes ending your commit message and before the
list of files with their change-counts.
Example:
<pre>
From 12345abcde Mon Sep 12 00:00:00 2001
From: Git Commiter <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 thisline.
---
***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
(...)
</pre>
=== Versioned Patches ===


Some hints about formatting your commit messages:
If an updated versioned of your patch series is called for, it should be sent
* if closing a bug write it in the first line of the commit log
as a new series rather than as reply to the old series. (For trivial/short
* limit the first line at 70 chars so headers and reply will fit in 80 characters. Mutt users will thank you.
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:
 
Please list all the changes to the previous versions in the ''commit summary
section'' as shown in the above example.
 
If your series has a cover letter, also summarize all changes in it as well.
 
<source lang="bash">
# git format-patch -o my-patches/ --subject-prefix="PATCH v2 container" master..my_branch
</source>
 
=== Shortcuts ===
 
For convenience you can store the pve-devel email address and the repository's
default subject prefices in your repository clones' configurations as follows:
 
<source lang="bash">
# git config --local sendemail.to pve-devel@pve.proxmox.com
# git config format.subjectprefix 'PATCH container'
</source>
 
Now the commands to create and send patches become:
<source lang="bash">
# git format-patch -o my-patches/ master..my_branch
# git send-email --compose my-patches/00*.patch
</source>


== Proxmox VE 2.0 API Clients ==
== Proxmox VE 2.0 API Clients ==

Revision as of 09:27, 11 October 2016

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/addition).

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.

PVE Development List: http://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Archive: http://pve.proxmox.com/cgi-bin/mailman/private/pve-devel/

Access to Code Repository (git)

https://git.proxmox.com

Build instructions

You could find build instruction here :

https://git.proxmox.com/?p=pve-common.git;a=blob_plain;f=README.dev;hb=HEAD

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

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 first line of the commit is not longer than 70 characters.
  • In the rest of the message, limit the line length to 80 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
# git commit -s -a

Preparing Patches

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 mant 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

Sending patches:

# git send-email --to=pve-devel@pve.proxmox.com --compose 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-leter, 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 Commiter <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 thisline.

---
 ***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
(...)

Versioned Patches

If an updated versioned of your patch series is called for, it should be sent as a new series rather than as reply to the old series. (For trivial/short 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:

Please list all the changes to the previous versions in the commit summary section as shown in the above example.

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

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

Shortcuts

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

# git config --local sendemail.to pve-devel@pve.proxmox.com
# git config format.subjectprefix 'PATCH container'

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

Proxmox VE 2.0 API Clients

php : https://github.com/CpuID/pve2-api-php-client

perl : http://search.cpan.org/~djzort/Net-Proxmox-VE-0.006/

python: https://github.com/remofritzsche/proxmox-utils

python: https://github.com/Daemonthread/pyproxmox

java: https://github.com/Elbandi/pve2-api-java

nodejs: https://www.npmjs.org/package/proxmox

Bugtracker (bugzilla)

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 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.

See Also