Developer Documentation - Revision history

Hd--: /* Development Package Repository */

2023-12-13T12:44:08Z

Development Package Repository

← Older revision		Revision as of 12:44, 13 December 2023
Line 31:		Line 31:
	Add the following to the <code>/etc/apt/sources.list</code> file:		Add the following to the <code>/etc/apt/sources.list</code> file:

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

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

Tlamprecht: /* Example */

2023-10-10T09:13:40Z

Example

← Older revision		Revision as of 09:13, 10 October 2023
Line 248:		Line 248:
	=== Example ===		=== Example ===

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

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

Tlamprecht: /* Example */

2023-10-10T09:13:29Z

Example

← Older revision		Revision as of 09:13, 10 October 2023
Line 250:		Line 250:
	To send the last two commits for a Proxmox VE project to the Proxmox VE development list you could then execute:		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		git send-email --to="pbs-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.		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.

Tlamprecht: /* Sending Patches */

2023-10-10T09:13:15Z

Sending Patches

← Older revision		Revision as of 09:13, 10 October 2023
Line 225:		Line 225:
	== Sending Patches ==		== 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.		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 ===		=== Tutorial ===

	See https://git-send-email.io/ for an interactive tutorial on ~~setting~~ up <code>git send-email</code>.		See https://git-send-email.io/ for an interactive tutorial to set up <code>git send-email</code>.

	=== Using Authenticated SMTP Server ===		=== 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:		<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]		[sendemail]
	smtpencryption = tls		smtpencryption=tls
	smtpserver = webmail.example.com		smtpserver=webmail.example.com
	smtpserverport = 587		smtpserverport=587
	smtpuser = j.smith@example.com		smtpuser=j.smith@example.com
	smtpsslcertpath =		smtpsslcertpath=
	confirm = always		confirm = always

	Add this to your global user <code>~/.gitconfig</code> or to the per project <code>.git/config</code>.		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 ~~once~~ for the password ~~when~~ sending.		<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) ==

Tlamprecht: /* Software License and Copyright */

2023-10-10T09:10:00Z

Software License and Copyright

← Older revision		Revision as of 09:10, 10 October 2023
Line 253:		Line 253:

	== Software License and Copyright ==		== Software License and Copyright ==
		⚫	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 require that contributors send us a contributor license agreement form by email to <code>office@proxmox.com</code>.
⚫	We only include code licensed under GNU Affero General Public License, version 3 http://www.gnu.org/licenses/agpl-3.0.html.
		⚫	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.
⚫	~~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.
			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 264:		Line 265:
	* and one for [http://www.proxmox.com/downloads/item/proxmox-entity-contributor-assignment-agreement entities contributors] (companies, foundations, or other organizations).		* and one for [http://www.proxmox.com/downloads/item/proxmox-entity-contributor-assignment-agreement 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.		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 ==		== See Also ==

Tlamprecht at 09:08, 10 October 2023

2023-10-10T09:08:42Z

← Older revision		Revision as of 09:08, 10 October 2023
Line 15:		Line 15:
	== Access to Code Repository (git) ==		== 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"~~.		You can find all of our project repositories at https://git.proxmox.com.
			The repositories relating to Proxmox Backup are under the section titled "rust".

	https://git.proxmox.com

	== Build instructions ==		== Build instructions ==
Line 51:		Line 50:
	The codebase is mostly Rust, with JavaScript for the web-interface.		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 ~~[http~~://docs.sencha.com/extjs/6.0.1/~~index.html here~~.]		We use the ExtJS framework for the GUI components; its API documentation can be found at: https://docs.sencha.com/extjs/7.0.0/.

	=== Using git ===		=== Using git ===
Line 78:		Line 77:
	# git diff master..my_branch		# git diff master..my_branch
	</source>		</source>


	==== Commits and Commit Messages ====		==== Commits and Commit Messages ====

	~~After~~ ~~making~~ ~~changes,~~ commit ~~them~~ (try to make small, self-contained commits) and include a sign-off line (-s).		Then, make your commit (try to make small, but 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~~.		* Make sure the '''line-length''' (text-width, column count) of the commit's message is '''not longer than 70 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 should '''not''' be split.
	* If it fixes a bug, start with that information, in the form: <code>fix #1234: summary here</code>
	* If it ~~implements~~ a ~~feature~~ ~~tracked~~ on ~~Bugzilla,~~ ~~use~~: <code>~~close~~ #1234: summary here</code>~~, albeit <code>fix #1234:</code> is commonly used and also fine.~~		* If it 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
⚫	* ~~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 <code>~~api~~: ~~datastore~~: summary here</code>
			* Try to add a tag denoting the subsystem at start, if an obvious choice exists.
⚫	: ~~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.
		⚫	** For example, if you changed the QEMU UI component in pve-manager, a possible tag could be <code>ui: qemu: summary here</code>
			** Don't add tags for things that are already clear from context, for example, adding a <code>kernel</code> tag for a patch in the kernel 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.

	~~The~~ ~~following~~ ~~command~~ ~~will take all~~ the ~~changes~~ in ~~tracked~~ ~~files~~ ~~and~~ commit ~~them~~:		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 rebase to re-order, drop, squash/fixup and edit both the whole commit or just rewording its message:
	<source lang="bash">
⚫	# git commit -s -a
	</source>

			git rebase -i --autosquash --autostash origin/master
⚫	New files won't get added automatically ~~with this command~~. To ~~stage~~ ~~new~~ or changed files ~~for~~ a commit, use:

			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.
	<source lang="bash">
			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
⚫	# git add newfile1.rs file2.rs
	</source>

⚫	You can always look at what will be ~~committed~~ with:

			The following command will take all changes of tracked files and add it to the commit:
	<source lang="bash">
	# git ~~diff~~ --~~staged~~		# git commit -s -a

	</source>
		⚫	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 ==		== Preparing Patches ==

Tlamprecht at 11:51, 2 February 2022

2022-02-02T11:51:07Z

← Older revision		Revision as of 11:51, 2 February 2022
Line 32:		Line 32:
	Add the following to the <code>/etc/apt/sources.list</code> file:		Add the following to the <code>/etc/apt/sources.list</code> file:

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

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

Martin: page created

2020-10-28T08:59:53Z

page created

New page

== 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 <code>/etc/apt/sources.list</code> 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: <nowiki>git://git.proxmox.com/git/</nowiki>
<source lang="bash">
# git clone git://git.proxmox.com/git/proxmox-backup.git
</source>
To update an already cloned project to the current version use:
<source lang="bash">
# git pull
</source>

== 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 [http://docs.sencha.com/extjs/6.0.1/index.html 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:

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

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:

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

After this, you can start working on your improvements. You can compare your changes to the current PBS master branch easily with:
<source lang="bash">
# git diff master..my_branch
</source>

==== 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: <code>fix #1234: summary here</code>
* If it implements a feature tracked on Bugzilla, use: <code>close #1234: summary here</code>, albeit <code>fix #1234:</code> 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 <code>api: datastore: summary here</code>
: 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:

<source lang="bash">
# git commit -s -a
</source>

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

<source lang="bash">
# git add newfile1.rs file2.rs
</source>

You can always look at what will be committed with:

<source lang="bash">
# git diff --staged
</source>

== Preparing Patches ==

{{note| We need a valid [[#Software License and Copyright|CLA]] to include your changes|reminder}}

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 <tt>proxmox-backup</tt> package:

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

Explain in the cover letter the aim of your patches:

<source lang="bash">
edit my-patches/0000-cover-letter.patch
</source>

Sending patches:

<source lang="bash">
# git send-email --to=pbs-devel@lists.proxmox.com 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-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:

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

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:

<source lang="bash">
# 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/*
</source>

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:

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

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:

<pre>
Acked-by: name / email address
</pre>

=== 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:

<source lang="bash">
$ git config --local sendemail.to pbs-devel@lists.proxmox.com
$ git config --local format.subjectprefix 'PATCH proxmox-backup'
$ git config --local format.signoff true
</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>

== 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 on setting up <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 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 [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:
* one for [http://www.proxmox.com/downloads/item/proxmox-individual-contributor-license-agreement individual contributors]
* and one for [http://www.proxmox.com/downloads/item/proxmox-entity-contributor-assignment-agreement 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 ==

* [https://git-scm.com/documentation Git Documentation]