diff options
author | Mike Rapoport <rppt@linux.ibm.com> | 2020-06-09 16:52:11 +0300 |
---|---|---|
committer | Andrei Vagin <avagin@gmail.com> | 2020-10-20 10:18:24 +0300 |
commit | d0fcb01d47de8d5c659cc09d0ab5d994d10b5ffa (patch) | |
tree | 08c7aaa4bc802bb58d17a7847591c375b3aeddfe /CONTRIBUTING.md | |
parent | 808684c99eb4c0cf12a5725cd6bbe3fea191273c (diff) |
CONTRIBUTING.md: import "How to submit patches" from criu.org
Import "How to submit patches" article from CRIU wiki and update its
format to match GitHub markdown.
Signed-off-by: Mike Rapoport <rppt@linux.ibm.com>
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 200 |
1 files changed, 199 insertions, 1 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 342619e88..edb7ecb48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,6 +14,204 @@ Here are some useful hints to get involved. * CRIU does need [extensive testing](https://github.com/checkpoint-restore/criu/issues?q=is%3Aissue+is%3Aopen+label%3Atesting); * Documentation is always hard, we have [some information](https://criu.org/Category:Empty_articles) that is to be extracted from people's heads into wiki pages as well as [some texts](https://criu.org/Category:Editor_help_needed) that all need to be converted into useful articles; * Feedback is expected on the github issues page and on the [mailing list](https://lists.openvz.org/mailman/listinfo/criu); -* We accept github pull requests and this is the preferred way to contribute to CRIU. If you prefer to send patches by email, you are welcome to send them to [the devel list](http://criu.org/How_to_submit_patches); +* We accept github pull requests and this is the preferred way to contribute to CRIU. If you prefer to send patches by email, you are welcome to send them to [CRIU development mailing list](https://lists.openvz.org/mailman/listinfo/criu). +Below we describe in more detail recommend practices for CRIU developemnt. * Spread the word about CRIU in [social networks](http://criu.org/Contacts); * If you're giving a talk about CRIU -- let us know, we'll mention it on the [wiki main page](https://criu.org/News/events); + +### Seting up the developemnt environment + +Although criu could be run as non-root (see [Security](https://criu.org/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. Official CRIU repo is at 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: + +``` + git clone https://github.com/checkpoint-restore/criu criu + cd criu + git checkout criu-dev +``` + +### Compile + +First, you need to install compile-time dependencies. Check [Installation dependencies](https://criu.org/Installation#Dependencies) for more info. + +To compile CRIU, run: + +``` + make +``` + +This should create the `./criu/criu` 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 +* CRIU mostly follows [Linux kernel coding style](https://www.kernel.org/doc/Documentation/process/coding-style.rst), 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 +``` + +The command runs [ZDTM Test Suite](https://criu.org/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. + +## 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: + +### 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. + +then you just add a line saying + +``` + Signed-off-by: Random J Developer <random at developer.example.org> +``` + +using your real name (please, no pseudonyms or anonymous contributions if +it possible). + +Hint: you can use `git commit -s` to add Signed-off-by line to your +commit message. To append such line to a commit you already made, use +`git commit --amend -s`. + +``` + From: Random J Developer <random at developer.example.org> + 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 +``` + +## 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 [GitHub](https://github.com) and create a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) + +Historically, CRIU worked with mailing lists and patches so if you still prefer this way continue reading till the end of this section. + +### 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 `git send-email` + +``` + git send-email --cover-letter --no-chain-reply-to --annotate \ + --confirm=always --to=criu@openvz.org criu-dev +``` + +Note that the `git send-email` 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 `--to=criu@openvz.org` 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 `---` 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 `--subject-prefix=PATCHv2` appended to +`git send-email` (substitute `v2` with the correct +version if needed though). + +### Mail patches + +The patches should be sent to CRIU development mailing list, `criu AT openvz.org`. 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). + +{{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}} + +### 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 + +Wiki article: [Continuous integration](https://criu.org/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 [enable Travis CI for your repo](https://criu.org/Continuous_integration#Enable_Travis_CI_for_your_repo) to check patches in your git branch, before sending them to the mailing list. |