Line 1: |
Line 1: |
− | == Obtaining the source code == | + | == Set up working environment == |
| | | |
− | The CRIU sources are tracked by Git SCM at http://git.criu.org
| + | 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. |
− | repository. You either could download packed sources or use git
| |
− | tool itself.
| |
| | | |
− | For example to clone criu one need to type
| + | == Get the source code == |
| | | |
− | git clone git://git.criu.org/crtools.git
| + | The CRIU sources are tracked by Git. Official CRIU repo is at [https://github.com/checkpoint-restore/criu https://github.com/checkpoint-restore/criu]. |
| | | |
− | == Changing the source code ==
| + | The repository may contain multiple branches. Development happens in the '''criu-dev''' branch. |
| | | |
− | When you change the source code keep in mind - we prefer tabs and
| + | To clone CRIU repo and switch to the proper branch, run: |
− | indentations to be 8 characters width. Consider reading [https://www.kernel.org/doc/Documentation/CodingStyle Linux kernel coding style].
| |
| | | |
− | Other "rules" could be learned from the source code - just make your code
| + | <pre><nowiki> |
− | to look similar.
| + | git clone https://github.com/checkpoint-restore/criu criu |
| + | cd criu |
| + | git checkout criu-dev |
| + | </nowiki></pre> |
| | | |
− | == Producing a patch == | + | == Compile == |
| | | |
− | There are at least two ways to make it right.
| + | First, you need to install compile-time dependencies. Check [[Installation#Dependencies]] for more info. |
| | | |
− | 1) git format-patch
| + | To compile CRIU, run: |
| | | |
− | You might need to read documentation on Git SCM how to prepare patch
| + | make |
− | 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
| + | This should create the <code>./criu/criu</code> executable. |
− | at all.
| + | |
| + | == 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 |
| + | * CRIU mostly follows [https://www.kernel.org/doc/Documentation/process/coding-style.rst Linux kernel coding style], but we are less strict than the kernel community. |
| + | |
| + | 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 == |
| + | |
| + | CRIU comes with an extensive test suite. To check whether your changes introduce any regressions, run |
| + | |
| + | make test |
| | | |
− | 2) Use "diff -up"
| + | The command runs [[ZDTM Test Suite]]. Check for any error messages produced by it. |
| | | |
− | Use <code>diff -up</code> or <code>diff -uprN</code> to create patches.
| + | 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. |
| | | |
− | == Signing your work == | + | == Sign your work == |
| | | |
− | To improve tracking of who did what we've introduced a "sign-off" procedure | + | To improve tracking of who did what, we ask you to sign off the patches |
− | on patches that are being emailed around.
| + | that are to be emailed. |
| | | |
| The sign-off is a simple line at the end of the explanation for the | | 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 | | patch, which certifies that you wrote it or otherwise have the right to |
− | pass it on as a open-source patch. The rules are pretty simple: if you | + | pass it on as an open-source patch. The rules are pretty simple: if you |
| can certify the below: | | can certify the below: |
| | | |
− | Developer's Certificate of Origin 1.1
| + | <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: | | By making a contribution to this project, I certify that: |
| | | |
Line 67: |
Line 90: |
| maintained indefinitely and may be redistributed consistent with | | maintained indefinitely and may be redistributed consistent with |
| this project or the open source license(s) involved. | | 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 |
| | | |
Line 73: |
Line 96: |
| | | |
| 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). |
| | | |
− | == An example of patch message == | + | 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> |
Line 86: |
Line 115: |
| --- | | --- |
| Patch body here | | Patch body here |
| + | </div></div> |
| + | |
| + | == Submit your work upstream == |
| + | |
| + | We accept github pull requests and this is the preferred way to contribute to CRIU. |
| + | For that you should push your work to your fork of CRIU at [https://github.com GitHub] and create a [https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests pull request] |
| | | |
− | == Checking patches for errors ==
| + | Historically, CRIU worked with mailing lists and patches so if you still prefer this way continue reading till the end of this section. |
− | Basic style error checking is provided by scripts/checkpatch.pl script
| |
− | from linux kernel source tree. You might have headers or complete sources
| |
− | of linux kernel at /usr/src/. Run | |
− | checkpatch.pl my_patch.patch (consider --no-tree option for headers-only)
| |
− | It will produce detailed report on style problems in your patch.
| |
− | Make sure to fix all _errors_(some warnings may be ignored).
| |
| | | |
− | To check whether your patches don't harm anything run | + | === Make a patch === |
− | make test
| + | |
− | It will launch [[ZDTM_Test_Suite]]. Check for error messages produced by it. | + | To create a patch, run |
− | You may also want to run other tests(rpc, libcriu, security etc) from test/ dir.
| + | |
| + | 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). |
| + | |
| + | === Mail patches === |
| | | |
− | == Mailing 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. |
| | | |
− | The patches should be sent to CRIU development mailing list
| + | Please make sure the email client you're using doesn't screw your patch (line wrapping and so on). |
− | which is located at https://openvz.org/mailman/listinfo/criu
| |
| | | |
− | Please make sure the email client you're using doesn't screw
| + | {{Note| When sending a patch set that consists of more than one patch, please, push your changes in your local repo and provide the URL of the branch in the cover-letter}} |
− | your patch (line wrapping and so on). | |
| | | |
− | == Wait for response == | + | === Wait for response === |
| | | |
| Be patient. Most CRIU developers are pretty busy people so if | | Be patient. Most CRIU developers are pretty busy people so if |
− | there is no immediate response on your patch - don't be surprised, | + | 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. | + | sometimes a patch may fly around a week before it gets reviewed. |
− | But definitely the patches will not go to <code>/dev/null</code>.
| + | |
| + | == 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]] | | [[Category:Development]] |