Difference between revisions of "Developer Documentation"

not longer than 70 characters

# git clone git://git.proxmox.com/git/pve-manager.git

# git pull

# git checkout -f -b my_branch master

# git diff master..my_branch

Fix #1234: summary here
Close #1234: summary here
# git commit -s -a

pve-container
# rm -rf my-patches/       # to clean left-overs
# git format-patch -o my-patches/ --subject-prefix="PATCH container" master..my_branch

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

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

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

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

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

@@ Line 43: / Line 43: @@
 </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">
-# git commit -a
+# git commit -s -a
 </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">
-# 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>
-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">
-# 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>
+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 ==

Difference between revisions of "Developer Documentation"

Revision as of 09:27, 11 October 2016

Contents

Introduction

Mailing List

Access to Code Repository (git)

Build instructions

Checking out a git repository

Preparing Patches

Versioned Patches

Shortcuts

Proxmox VE 2.0 API Clients

Bugtracker (bugzilla)

Software License and Copyright

See Also

Navigation menu

Search