|
| 1 | +--- |
| 2 | +title: Submitting changes to the KraftKit repository |
| 3 | +description: | |
| 4 | + New features, bugfixes, improvements, maintenance and everything in between |
| 5 | + as contributions are welcome! |
| 6 | +--- |
| 7 | + |
| 8 | +The Unikraft project is an open source and encourages the fostering open |
| 9 | +collaboration. If you are reading this guide on how to submit changes, then |
| 10 | +thank you in advance! |
| 11 | + |
| 12 | +Unikraft's source code is hosted on [GitHub](https://github.com). This includes |
| 13 | +the Unikraft core repository, auxiliary external microlibraries, applications, |
| 14 | +platforms, architectures and additional tools like `kraft`. Any of these |
| 15 | +repositories follow the same submission process for changes: the pull request. |
| 16 | + |
| 17 | +Make sure one pull request covers only one topic. |
| 18 | + |
| 19 | +### Submission Checklist |
| 20 | + |
| 21 | +When you make a submission, please make sure you follow the steps below, also |
| 22 | +part of the pull request template: |
| 23 | + |
| 24 | +- [ ] Read the contribution guidelines in this page regarding submitting new changes to the project; |
| 25 | +- [ ] Test your changes against relevant architectures and platforms; |
| 26 | +- [ ] Ran `make fmt` on your commit series before opening this PR; |
| 27 | +- [ ] Update relevant documentation. |
| 28 | + |
| 29 | +The pull request template will also request you to write a description of changes. |
| 30 | + |
| 31 | +## Commits |
| 32 | + |
| 33 | +Make sure each commit corresponds to one code / content change only. |
| 34 | + |
| 35 | +Please create descriptive commit messages. Consider using a prefix for the |
| 36 | +commit message. Add a detailed description on the motivation for the commit and |
| 37 | +summary of changes. Follow [this guide](https://cbea.ms/git-commit/) on writing |
| 38 | +good commit messages. |
| 39 | + |
| 40 | +Each commit must be authored by adding a `Signed-off-by` message. Use the |
| 41 | +`-s|--signoff` option of the `git` command when creating a commit. |
| 42 | + |
| 43 | +### Commit Message Format |
| 44 | + |
| 45 | +In order to simplify reading and searching the patch history, please use the following format for the short commit message: |
| 46 | + |
| 47 | +```txt |
| 48 | +[selector]([package]): [Your short message] |
| 49 | +``` |
| 50 | + |
| 51 | +Where `[selector]` can be one of the following: |
| 52 | + |
| 53 | +| Selector | Description | |
| 54 | +|-------------|-----------------------------------------------| |
| 55 | +| `build` | Changes generated when building dependencies. | |
| 56 | +| `ci` | Changes to the ci workflows. | |
| 57 | +| `docs` | Changes to the documentation. | |
| 58 | +| `feat` | Changes introducing a new feature. | |
| 59 | +| `fix` | Changes introducing a fix. | |
| 60 | +| `perf` | Changes improving the performance. | |
| 61 | +| `refactor` | Changes that refactor code. | |
| 62 | +| `style` | Changes related to coding style. | |
| 63 | +| `test` | Changes related to tests. | |
| 64 | +| `revert` | Changes reverting previous commits. | |
| 65 | +| `gomod` | Changes to the `go.mod` file. | |
| 66 | + |
| 67 | +> Commit titles must be at most 75 characters long, and each line in the commit message must be at most 74 characters long. |
| 68 | +
|
| 69 | +Usually, a commit will involve changes to a single package. In case the changes span over multiple packages, the ``([package])`` |
| 70 | +portion of the commit title can be omitted. |
| 71 | + |
| 72 | +In the case the changes are related to the dependencies of `KraftKit` and not `kraft` itself, `deps` is used as a placeholder for `[package]`. |
| 73 | + |
| 74 | +The short message part should start with a capital and be formulated in simple present. |
| 75 | + |
| 76 | +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. |
| 77 | +It is important to provide enough information to allow `reviewers` and other developers to understand the commit's purpose. |
| 78 | + |
| 79 | +### Developer's Certificate of Origin |
| 80 | + |
| 81 | +Please note that all commits **must be signed off**. |
| 82 | +This is required so that you certify that you submitted the patch under the [Developer's Certificate of Origin](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1). |
| 83 | + |
| 84 | +```txt |
| 85 | +Developer's Certificate of Origin 1.1 |
| 86 | +
|
| 87 | +By making a contribution to this project, I certify that: |
| 88 | +(a) The contribution was created in whole or in part by me and I |
| 89 | + have the right to submit it under the open source license |
| 90 | + indicated in the file; or |
| 91 | +
|
| 92 | +(b) The contribution is based upon previous work that, to the best |
| 93 | + of my knowledge, is covered under an appropriate open source |
| 94 | + license and I have the right under that license to submit that |
| 95 | + work with modifications, whether created in whole or in part |
| 96 | + by me, under the same open source license (unless I am |
| 97 | + permitted to submit under a different license), as indicated |
| 98 | + in the file; or |
| 99 | +
|
| 100 | +(c) The contribution was provided directly to me by some other |
| 101 | + person who certified (a), (b) or (c) and I have not modified |
| 102 | + it. |
| 103 | +
|
| 104 | +(d) I understand and agree that this project and the contribution |
| 105 | + are public and that a record of the contribution (including all |
| 106 | + personal information I submit with it, including my sign-off) is |
| 107 | + maintained indefinitely and may be redistributed consistent with |
| 108 | + this project or the open source license(s) involved. |
| 109 | +``` |
| 110 | + |
| 111 | +Signing off is done by adding the following line after the long commit message: |
| 112 | + |
| 113 | +```txt |
| 114 | +Signed-off-by: $FULL_NAME <$EMAIL> |
| 115 | +``` |
| 116 | + |
| 117 | +You can also use the `--signoff` or `-s` parameter of `git commit` when writing commit messages. |
| 118 | + |
| 119 | +### Example Commit Message |
| 120 | + |
| 121 | +```txt |
| 122 | +feat(foo): Add new trondle calls |
| 123 | +
|
| 124 | +Add some new trondle calls to the foobar interface to support the new |
| 125 | +zot feature. |
| 126 | +
|
| 127 | +Signed-off-by: John Smith <[email protected]> |
| 128 | +``` |
| 129 | + |
| 130 | +## Addressing Multiple Authors |
| 131 | + |
| 132 | +It is common that new code introduced into Unikraft comes from multiple authors. |
| 133 | +Each author should have their name added as part of the respective commit. |
| 134 | + |
| 135 | +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. |
| 136 | + |
| 137 | +Each author **must** add a `Signed-off-by` message, in order to certify that the submission is published under the [`DCO`](https://wiki.linuxfoundation.org/dco). |
| 138 | + |
| 139 | +## Rebasing and Squashing |
| 140 | + |
| 141 | +While working on a pull request, the destination branch may change. |
| 142 | +This will require [rebasing](https://docs.github.com/en/get-started/using-git/about-git-rebase) the source branch to keep it in sync. |
| 143 | +There may be conflicts that need to be solved as part of the rebase. |
| 144 | + |
| 145 | +As you want to create on commit for each content change, [squashing multiple commits](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-commits/squashing-commits) into one may be required. |
| 146 | +This may be either because of different small changes added to the pull request as new commits. |
| 147 | +Or due to [incorporating suggested changes](docs/contributing/suggest-changes). |
0 commit comments