Skip to content

Commit 26c2f15

Browse files
committed
docs/contributing: Add KraftKit contributing page
This page is largely based on the Unikraft core contributing page and contains details about the conventions used in KraftKit. Signed-off-by: Luca Seritan <[email protected]>
1 parent 0a4ec52 commit 26c2f15

File tree

1 file changed

+147
-0
lines changed

1 file changed

+147
-0
lines changed
Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
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

Comments
 (0)