The Unikraft project is an open source and encourages the fostering open collaboration. If you are reading this guide on how to submit changes, then thank you in advance!
Unikraft's source code is hosted on GitHub. This includes
the Unikraft core repository, auxiliary external microlibraries, applications,
platforms, architectures and additional tools like kraft
. Any of these
repositories follow the same submission process for changes: the pull request.
Make sure one pull request covers only one topic.
When you make a submission, please make sure you follow the steps below, also part of the pull request template:
checkpatch.pl
on your commit series before opening this PR;The pull request template will also request you to fill additional configuration information and a description of changes.
Make sure each commit corresponds to one code / content change only.
Please create descriptive commit messages. Consider using a prefix for the commit message. Add a detailed description on the motivation for the commit and summary of changes. Follow this guide on writing good commit messages.
Each commit must be authored by adding a Signed-off-by
message. Use the
-s|--signoff
option of the git
command when creating a commit.
In order to simplify reading and searching the patch history, please use the following format for the short commit message:
[selector]/[component name]: [Your short message]
Where [selector]
can be one of the following:
Selector | Description |
---|---|
arch | Patch for the architecture code in arch/ , [component] is the architecture (e.g, x86_64 or arm64 ) applies also for corresponding headers in include/uk/arch/ . |
plat | Patch for one of the platform libraries in plat/ , [component] is the platform (e.g, qemu , firecracker or xen ). This applies also for corresponding headers in include/uk/plat/ |
include | Changes to general Unikraft headers (e.g. include/ , include/uk ). |
lib | Patch for one of the Unikraft base libraries (not external) in lib/ , [component] is the library name without lib prefix (e.g, fdt ). |
build | Changes to build tool or generic configurations, [component] is optional. |
Commit messages, along with all source files follow a 80-character rule.
If no [selector]
applies, define your own and cross your fingers that the reviewer(s)
do(es) not complain. :-)
Sometimes a single change required multiple commit identifiers.
In general this should be avoided by splitting a commits into multiple ones.
But for the rare case use a comma separated list of identifiers and/or use an asterisk for [component]
(according to the sense).
For example:
lib/nolibc, plat/xen: Add support for foobararch/*: Add spinlocks
The short message part should start with a capital and be formulated in simple present.
The long message part is pretty free form but should be used to explain the reasons for the commit, what has been changed and why.
It is important to provide enough information to allow reviewers
and other developers to understand the commit's purpose.
Please note that all commits must be signed off. This is required so that you certify that you submitted the patch under the Developer's Certificate of Origin.
Developer's Certificate of Origin 1.1By making a contribution to this project, I certify that:(a) The contribution was created in whole or in part by me and Ihave the right to submit it under the open source licenseindicated in the file; or(b) The contribution is based upon previous work that, to the bestof my knowledge, is covered under an appropriate open sourcelicense and I have the right under that license to submit thatwork with modifications, whether created in whole or in partby me, under the same open source license (unless I ampermitted to submit under a different license), as indicatedin the file; or(c) The contribution was provided directly to me by some otherperson who certified (a), (b) or (c) and I have not modifiedit.(d) I understand and agree that this project and the contributionare public and that a record of the contribution (including allpersonal information I submit with it, including my sign-off) ismaintained indefinitely and may be redistributed consistent withthis project or the open source license(s) involved.
Signing off is done by adding the following line after the long commit message:
Signed-off-by: $FULL_NAME <$EMAIL>
You can also use the --signoff
or -s
parameter of git commit
when writing commit messages.
lib/ukdebug: Add new trondle callsAdd some new trondle calls to the foobar interface to support the newzot feature.Signed-off-by: John Smith <j.smith@unikraft.org>
It is common that new code introduced into Unikraft comes from multiple authors. Each author should have their name added as part of the respective commit.
Unikraft OSS project adopts a similar process seen with the Linux kernel, where a new merge request or PR can have multiple authors, multiple reviewers, testers, acknowledgements and more.
Each author must add a Signed-off-by
message, in order to certify that the submission is published under the DCO
.
While working on a pull request, the destination branch may change. This will require rebasing the source branch to keep it in sync. There may be conflicts that need to be solved as part of the rebase.
As you want to create on commit for each content change, squashing multiple commits into one may be required. This may be either because of different small changes added to the pull request as new commits. Or due to incorporating suggested changes.
Feel free to ask questions, report issues, and meet new people.