mirror of
https://github.com/kata-containers/kata-containers.git
synced 2025-08-18 16:08:25 +00:00
docs: Add central contributing doc
This doc will be referenced by all the other Kata Containers repositories. Fixes #5. Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt
parent
2407245061
commit
c53875ed8f
266
CONTRIBUTING.md
Normal file
266
CONTRIBUTING.md
Normal file
@ -0,0 +1,266 @@
|
|||||||
|
# Contributing to the Kata Containers project
|
||||||
|
|
||||||
|
* [Code of Conduct](#code-of-conduct)
|
||||||
|
* [Golang Coding Style](#golang-coding-style)
|
||||||
|
* [Certificate of Origin](#certificate-of-origin)
|
||||||
|
* [Pull requests](#pull-requests)
|
||||||
|
* [Before starting work on a PR](#before-starting-work-on-a-pr)
|
||||||
|
* [Normal PR workflow](#normal-pr-workflow)
|
||||||
|
* [Re-vendor PRs](#re-vendor-prs)
|
||||||
|
* [Patch format](#patch-format)
|
||||||
|
* [Reviews](#reviews)
|
||||||
|
* [Examples](#examples)
|
||||||
|
* [Contact](#contact)
|
||||||
|
* [Project maintainers](#project-maintainers)
|
||||||
|
* [Issue tracking](#issue-tracking)
|
||||||
|
* [Closing issues](#closing-issues)
|
||||||
|
|
||||||
|
The Kata Containers project is an open source project licensed under the
|
||||||
|
[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
|
||||||
|
|
||||||
|
It comprises a number of repositories under the [GitHub Kata
|
||||||
|
Containers organisation](https://github.com/kata-containers). Unless
|
||||||
|
explicitly stated otherwise, all the Kata Containers repositories follow the
|
||||||
|
process documented here.
|
||||||
|
|
||||||
|
## Code of Conduct
|
||||||
|
|
||||||
|
All contributors must agree to the project [code of conduct](CODE_OF_CONDUCT.md).
|
||||||
|
|
||||||
|
## Golang Coding Style
|
||||||
|
|
||||||
|
The usual Go style, enforced by `gofmt`, should be used. Additionally, the [Go
|
||||||
|
Code Review](https://github.com/golang/go/wiki/CodeReviewComments) document
|
||||||
|
contains a few common errors to be mindful of.
|
||||||
|
|
||||||
|
## Certificate of Origin
|
||||||
|
|
||||||
|
In order to get a clear contribution chain of trust we use the [signed-off-by
|
||||||
|
language](https://ltsi.linuxfoundation.org/software/signed-off-process/)
|
||||||
|
used by the Linux kernel project.
|
||||||
|
|
||||||
|
## Pull requests
|
||||||
|
|
||||||
|
All the repositories accept contributions by a GitHub Pull request (PR).
|
||||||
|
|
||||||
|
### Before starting work on a PR
|
||||||
|
|
||||||
|
We welcome all contributions but to minimize the chance of multiple people
|
||||||
|
working on the same feature or bug fixes (yes, it has happened), we recommend
|
||||||
|
strongly that you raise a GitHub issue **before** you start working on a PR.
|
||||||
|
|
||||||
|
If you are a new contributor, you cannot assign the issue to yourself. In this
|
||||||
|
case, raise the issue and add a comment stating that you intend to work on the
|
||||||
|
issue yourself. This gives the team visibility of the work you plan to do.
|
||||||
|
|
||||||
|
The other advantage to raising the issue at the outset is that our process requires an
|
||||||
|
issue to be associated with every PR (see [patch format](#patch-format)).
|
||||||
|
|
||||||
|
### Normal PR workflow
|
||||||
|
|
||||||
|
Github has a basic introduction to the PR process
|
||||||
|
[here](https://help.github.com/articles/using-pull-requests/).
|
||||||
|
|
||||||
|
When submitting your PR, treat the PR message the same
|
||||||
|
you would a patch message, including pre-fixing the title with a subsystem
|
||||||
|
name.
|
||||||
|
|
||||||
|
By default, GitHub copies the message from your first patch, which is often
|
||||||
|
appropriate. However, ensure your message is accurate and complete for the
|
||||||
|
entire PR because it ends up in the Git log as the merge message.
|
||||||
|
|
||||||
|
Your PR might get feedback and comments, and require rework. The recommended
|
||||||
|
procedure for reworking is to redo your branch to a clean state and "force
|
||||||
|
push" it to your GitHub branch. A "forced push" is adequate, which is
|
||||||
|
reflected in the online comment history. Do not pile patches on patches to
|
||||||
|
rework your branch. You should rework any relevant information from the GitHub
|
||||||
|
comment section into your patch set because your patches are documented in the
|
||||||
|
Git log, not the comment section.
|
||||||
|
|
||||||
|
For more information on GitHub "force push" workflows see "[Why and how to
|
||||||
|
correctly amend GitHub pull
|
||||||
|
requests](http://blog.adamspiers.org/2015/03/24/why-and-how-to-correctly-amend-github-pull-requests/)".
|
||||||
|
|
||||||
|
Your PR can contain more than one patch. Use as many patches as necessary to
|
||||||
|
implement the request. Each PR should only cover one topic. If you mix up
|
||||||
|
different items in your patches or PR, they will likely need to be reworked.
|
||||||
|
|
||||||
|
### Re-vendor PRs
|
||||||
|
|
||||||
|
If you raise a PR to update the vendored copy of one or more golang packages,
|
||||||
|
there are two critical pieces of information you need to add to the commit
|
||||||
|
body:
|
||||||
|
|
||||||
|
- A brief explanation why the re-vendor is required.
|
||||||
|
|
||||||
|
For example, you should state if an important bug fix or new feature is
|
||||||
|
required, or if a particular commit is needed.
|
||||||
|
|
||||||
|
- The range of commits being added for these third-party packages.
|
||||||
|
|
||||||
|
It is possible that re-vendoring a particular package will also result in
|
||||||
|
updates to other dependent packages. However, it is important to include the
|
||||||
|
commit range (even if it is big) for the primary package(s) the re-vendor PR
|
||||||
|
is raised for.
|
||||||
|
|
||||||
|
These details allow for easier troubleshooting if the re-vendor PR
|
||||||
|
introduces bug or behavioral changes.
|
||||||
|
|
||||||
|
Generate the list of new commits added to the primary re-vendored
|
||||||
|
package by comparing the previous and latest commits for the package being re-vendored.
|
||||||
|
|
||||||
|
The following example lists the steps you should take if a new version of
|
||||||
|
`libcontainer` (part of the `runc` repository) is required:
|
||||||
|
|
||||||
|
1. Determine the previous and latest commits for the package by looking at
|
||||||
|
the `diff` of the `Gopkg.toml` file in your branch.
|
||||||
|
|
||||||
|
1. Run the commands below:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ cd $GOPATH/src/github.com/opencontainers/runc
|
||||||
|
$ old_commit="..."
|
||||||
|
$ new_commit="..."
|
||||||
|
$ git log --no-merges --abbrev-commit --pretty=oneline "${old_commit}..${new_commit}") | sed 's/^/ /g'
|
||||||
|
```
|
||||||
|
|
||||||
|
Paste the output of the previous command directly into the commit "as-is".
|
||||||
|
Note that the four space indent added by the `sed` command is used to force
|
||||||
|
GitHub to render the list in a fixed-width font, which makes it easier to
|
||||||
|
read.
|
||||||
|
|
||||||
|
## Patch format
|
||||||
|
|
||||||
|
Beside the `Signed-off-by` footer, we expect each patch to comply with the
|
||||||
|
following format:
|
||||||
|
|
||||||
|
```
|
||||||
|
Subsystem: One line change summary
|
||||||
|
|
||||||
|
More detailed explanation of your changes: Why and how.
|
||||||
|
|
||||||
|
See:
|
||||||
|
http://chris.beams.io/posts/git-commit/
|
||||||
|
|
||||||
|
For some more good advice, and the Linux Kernel document:
|
||||||
|
https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches
|
||||||
|
|
||||||
|
Fixes: #nnn
|
||||||
|
|
||||||
|
Signed-off-by: <contributor@foo.com>
|
||||||
|
```
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
```
|
||||||
|
pod: Remove token from Cmd structure
|
||||||
|
|
||||||
|
The token and pid data will be hold by the new Process structure and
|
||||||
|
they are related to a container.
|
||||||
|
|
||||||
|
Fixes: #123
|
||||||
|
|
||||||
|
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
|
||||||
|
```
|
||||||
|
|
||||||
|
Correct formatting of the PR patches is verified using the
|
||||||
|
[checkcommits](https://github.com/kata-containers/tests/tree/master/cmd/checkcommits)
|
||||||
|
tool.
|
||||||
|
|
||||||
|
Note, that the body of the message should not just be a continuation of the
|
||||||
|
subject line, and is not used to extend the subject line beyond its length
|
||||||
|
limit. They should stand alone as complete sentence and paragraphs.
|
||||||
|
|
||||||
|
It is recommended that each of your patches fixes one thing. Smaller patches
|
||||||
|
are easier to review, more likely accepted and merged, and problems are more
|
||||||
|
likely to be identified during review.
|
||||||
|
|
||||||
|
## Reviews
|
||||||
|
|
||||||
|
Before your PRs are merged into the main code base, they are reviewed. We
|
||||||
|
encourage anybody to review any PR and leave feedback.
|
||||||
|
|
||||||
|
We use an "acknowledge" system for people to note if they agree or disagree
|
||||||
|
with a PR. We utilize some automated systems that can spot common acknowledge
|
||||||
|
patterns, which include placing any of these **at the beginning of a comment
|
||||||
|
line**:
|
||||||
|
|
||||||
|
- LGTM
|
||||||
|
- lgtm
|
||||||
|
- +1
|
||||||
|
- Approve
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
The following is an example of a valid "ack":
|
||||||
|
|
||||||
|
```
|
||||||
|
Excellent work - thanks for your contribution.
|
||||||
|
|
||||||
|
lgtm
|
||||||
|
```
|
||||||
|
|
||||||
|
The following comment is *not* valid because the magic "lgtm" does not start
|
||||||
|
at the beginning of the line:
|
||||||
|
|
||||||
|
```
|
||||||
|
I love it! Very clean code and great tests. lgtm.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contact
|
||||||
|
|
||||||
|
The Kata Containers community can be reached through its dedicated IRC
|
||||||
|
channels, Slack channels, and mailing lists:
|
||||||
|
|
||||||
|
* IRC:
|
||||||
|
* Development discussions: `#kata-dev @ freenode.net`.
|
||||||
|
* General discussions: `#kata-general @ freenode.net`.
|
||||||
|
|
||||||
|
* [Slack channels](https://katacontainers.slack.com/) ([invite](http://bit.ly/KataSlack)).
|
||||||
|
|
||||||
|
* [Mailing lists](http://lists.katacontainers.io/).
|
||||||
|
|
||||||
|
### Project maintainers
|
||||||
|
|
||||||
|
The Kata Containers project maintainers are the people accepting or
|
||||||
|
rejecting any PR. They are listed in the `OWNERS` files. There can be one
|
||||||
|
`OWNERS` file per directory.
|
||||||
|
|
||||||
|
The `OWNERS` files split maintainership into 2 categories: reviewers and
|
||||||
|
approvers. All approvers also belong to the reviewers list. There must be at
|
||||||
|
least one approval from one member of each list for a PR to be merged.
|
||||||
|
|
||||||
|
Since approvers are also reviewers, they technically can approve a PR without
|
||||||
|
getting another reviewer's approval. However, it is their due diligence to
|
||||||
|
rely on reviewers and should use their approval power only in very specific
|
||||||
|
cases.
|
||||||
|
|
||||||
|
## Issue tracking
|
||||||
|
|
||||||
|
To report a bug that is not already documented, please open a GitHub issue for
|
||||||
|
the repository in question.
|
||||||
|
|
||||||
|
If it is unclear which repository to raise your query against, first try to
|
||||||
|
get in [contact](#contact) with us. If in doubt, raise the issue
|
||||||
|
[here](https://github.com/kata-containers/community/issues/new) and we will
|
||||||
|
help you to handle the query by routing it to the correct area for resolution.
|
||||||
|
|
||||||
|
## Closing issues
|
||||||
|
|
||||||
|
Our tooling requires adding a `Fixes` comment to at least one commit in the PR,
|
||||||
|
which triggers GitHub to automatically close the issue once the PR is merged:
|
||||||
|
|
||||||
|
```
|
||||||
|
pod: Remove token from Cmd structure
|
||||||
|
|
||||||
|
The token and pid data will be hold by the new Process structure and
|
||||||
|
they are related to a container.
|
||||||
|
|
||||||
|
Fixes #123
|
||||||
|
|
||||||
|
Signed-off-by: Sebastien Boeuf <sebastien.boeuf@intel.com>
|
||||||
|
```
|
||||||
|
|
||||||
|
The issue is automatically closed by GitHub when the [commit
|
||||||
|
message](https://help.github.com/articles/closing-issues-via-commit-messages/)
|
||||||
|
is parsed.
|
||||||
Loading…
Reference in New Issue
Block a user