277
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − How to submit patches into the CRIU+ − =================================== + − Obtaining the source code+ − ------------------------- − + − repository. You either could download packed sources or use git − tool itself. − For example to clone crtools one need to type+ − git clone git://git.criu.org/crtools.git+ + + + + + − Changing the source code+ − ------------------------ − When you change the source code keep in mind -- we prefer tabs and+ − indentations to be 8 characters width. − Other "rules" could be learned from the source code -- just make your code+ − to look similar. + − Producing a patch+ − ----------------- − There are at least two ways to make it right.+ − 1) git format-patch+ − You might need to read documentation on Git SCM how to prepare patch+ − for mail submission. Take a look on http://book.git-scm.com/ and/or − http://git-scm.com/documentation for details. It should not be hard − at all. − 2) Use "diff -up"+ − Use "diff -up" or "diff -uprN" to create patches.+ + + + − Signing your work+ − ----------------- − + − on patches that are being emailed around. − + − + − pass it on as a open-source patch. The rules are pretty simple: if you+ − can certify the below:+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + − Developer's Certificate of Origin 1.1+ − By making a contribution to this project, I certify that:+ + − (a) The contribution was created in whole or in part by me and I+ − have the right to submit it under the open source license − indicated in the file; or − (b) The contribution is based upon previous work that, to the best+ − of my knowledge, is covered under an appropriate open source+ − license and I have the right under that license to submit that+ − work with modifications, whether created in whole or in part+ − by me, under the same open source license (unless I am+ − permitted to submit under a different license), as indicated+ − in the file; or+ − (c) The contribution was provided directly to me by some other+ − person who certified (a), (b) or (c) and I have not modified − it. − (d) I understand and agree that this project and the contribution+ − are public and that a record of the contribution (including all+ − personal information I submit with it, including my sign-off) is − maintained indefinitely and may be redistributed consistent with − this project or the open source license(s) involved. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Line 84:
Line 135: − + + + + − An example of patch message+ − + + − + − + + + + + + + + + − Long patch description (could be skipped if patch+ − is trivial enough) − Signed-off-by: Random J Developer <random at developer.example.org>+ − --- − Patch body here + − Mailing patches+ − --------------- − The patches should be sent to CRIU development mailing list+ − which is located at https://openvz.org/mailman/listinfo/criu+ + − Please make sure the email client you're using doesn't screw+ − your patch (line wrapping and so on). + − Wait for response+ − ----------------- − Be patient. Most CRIU developers are pretty busy people so if+ − there is no immediate response on your patch -- don't be surprised, − sometimes a patch may fly around a week(s) before it get reviewed. − But definitely the patches will not go to /dev/null. − ---+ − With best regards, − CRIU-team
→Make a patch: Fix git send-email example to use "criu-dev" instead of "master" branch
== Set up working environment ==
Although criu could be run as non-root (see [[Security]]), development is better to be done as root. For example, some tests require root. So, it would be a good idea to set up some recent Linux distro on a virtual machine.
== Get the source code ==
The CRIU sources are tracked by Git SCM at http://git.criu.org
The CRIU sources are tracked by Git. Official CRIU repo is at [https://github.com/checkpoint-restore/criu https://github.com/checkpoint-restore/criu].
The repository may contain multiple branches. Development happens in the '''criu-dev''' branch.
To clone CRIU repo and switch to the proper branch, run:
<pre><nowiki>
git clone https://github.com/checkpoint-restore/criu criu
cd criu
git checkout criu-dev
</nowiki></pre>
== Compile ==
First, you need to install compile-time dependencies. Check [[Installation#Dependencies]] for more info.
To compile CRIU, run:
make
This should create the <code>./criu/criu</code> executable.
== Edit the source code ==
If you use ctags, you can generate the ctags file by running
make tags
When you change the source code, please keep in mind the following code conventions:
* we prefer tabs and indentations to be 8 characters width
* consider reading [https://www.kernel.org/doc/Documentation/process/coding-style.rst Linux kernel coding style].
Other conventions can be learned from the source code itself. In short, make sure your new code
looks similar to what is already there.
== Test your changes ==
To improve tracking of who did what we've introduced a "sign-off" procedure
CRIU comes with an extensive test suite. To check whether your changes introduce any regressions, run
The sign-off is a simple line at the end of the explanation for the
make test
patch, which certifies that you wrote it or otherwise have the right to
The command runs [[ZDTM Test Suite]]. Check for any error messages produced by it.
In case you'd rather have someone else run the tests, you can use travis-ci for your
own github fork of CRIU. It will check the compilation for various supported platforms,
as well as run most of the tests from the suite. See https://travis-ci.org/checkpoint-restore/criu
for more details.
== Make a patch ==
To create a patch, run
git format-patch --signoff origin/criu-dev
You might need to read GIT documentation on how to prepare patches
for mail submission. Take a look at http://book.git-scm.com/ and/or
http://git-scm.com/documentation for details. It should not be hard
at all.
We recommend to post patches using <code>git send-email</code>
git send-email --cover-letter --no-chain-reply-to --annotate \
--confirm=always --to=criu@openvz.org criu-dev
Note that the <code>git send-email</code> subcommand may not be in
the main git package and using it may require installation of a
separate package, for example the "git-email" package in Fedora and
Debian.
If this is your first time using git send-email, you might need to
configure it to point it to your SMTP server with something like:
git config --global sendemail.smtpServer stmp.example.net
If you get tired of typing <code>--to=criu@openvz.org</code> all the time,
you can configure that to be automatically handled as well:
git config sendemail.to criu@openvz.org
If a developer is sending another version of the patch (e.g. to address
review comments), they are advised to note differences to previous versions
after the <code>---</code> line in the patch so that it helps reviewers but
doesn't become part of git history. Moreover, such patch needs to be prefixed
correctly with <code>--subject-prefix=PATCHv2</code> appended to
<code>git send-email</code> (substitute <code>v2</code> with the correct
version if needed though).
== Sign your work ==
To improve tracking of who did what, we ask you to sign off the patches
that are to be emailed.
The sign-off is a simple line at the end of the explanation for the
patch, which certifies that you wrote it or otherwise have the right to
pass it on as an open-source patch. The rules are pretty simple: if you
can certify the below:
<div class="toccolours mw-collapsible mw-collapsed" style="width: 46em;">
'''Developer's Certificate of Origin 1.1'''
<div class="mw-collapsible-content">
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
</div></div>
then you just add a line saying
then you just add a line saying
using your real name (please, no pseudonyms or anonymous contributions if
using your real name (please, no pseudonyms or anonymous contributions if
it possible)
it possible).
Hint: you can use <code>git commit -s</code> to add Signed-off-by line to your
commit message. To append such line to a commit you already made, use
<code>git commit --amend -s</code>.
<div class="toccolours mw-collapsible mw-collapsed" style="width: 46em;">
---------------------------
'''Example patch message'''
<div class="mw-collapsible-content">
From: Random J Developer <random at developer.example.org>
From: Random J Developer <random at developer.example.org>
Subject: [PATCH] Short patch description
Subject: [PATCH] Short patch description
Long patch description (could be skipped if patch
is trivial enough)
Signed-off-by: Random J Developer <random at developer.example.org>
---
Patch body here
</div></div>
== Mail patches ==
The patches should be sent to CRIU development mailing list, <code>criu AT openvz.org</code>. Note that you need to be subscribed first in order to post. The list web interface is available at https://openvz.org/mailman/listinfo/criu; you can also use standard mailman aliases to work with it.
Please make sure the email client you're using doesn't screw your patch (line wrapping and so on).
== Wait for response ==
Be patient. Most CRIU developers are pretty busy people so if
there is no immediate response on your patch — don't be surprised,
sometimes a patch may fly around a week before it gets reviewed.
== Continuous integration ==
''Main article: [[Continuous integration]]''
CRIU tests are run for each series sent to the mailing list. If you get a message from our patchwork that patches failed to pass the tests, you have to investigate what is wrong.
We also recommend you to [[Continuous integration#Enable Travis CI for your repo|enable Travis CI for your repo]] to check patches in your git branch, before sending them to the mailing list.
[[Category:Development]]