github/kata-containers
1
0
Fork 1
mirror of https://github.com/kata-containers/kata-containers.git synced 2025-08-26 03:29:02 +00:00
Code Issues Projects Releases Wiki Activity

docs: Fix spelling and formatting

Browse Source 
Updated the docs fixing spelling and formatting.

Fixes: #102.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
This commit is contained in:
James O. D. Hunt 2019-05-24 08:32:36 +01:00
parent 5421d4b9cd
commit a7ec16ddcb
9 changed files with 50 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
CONTRIBUTING.md
View File

@ -102,9 +102,9 @@ before submitting your PR.
> **Note:** To ensure you replicate the static checks performed by the CI system, it is
recommended that you:
> * Ensure you have a 'clean' source tree, as the checks will check all files present, and
> * Ensure you have a "clean" source tree, as the checks will check all files present, and
might fail if you have extra files or your files are out of date in your tree.
> * Ensure that [gometalinter](https://github.com/alecthomas/gometalinter) is current or
> * Ensure that [`gometalinter`](https://github.com/alecthomas/gometalinter) is current or
has not been installed (the static check scripts will install it if necessary). Changes
in either the linters used or the Kata Containers code base can produce spurious errors
that do not fail inside the CI systems.
@ -112,7 +112,7 @@ that do not fail inside the CI systems.
### Normal PR workflow
Github has a basic introduction to the PR process
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
@ -256,8 +256,8 @@ This is the official location for this repository and is referred to as the
repository" into your local repository.
You might ask how Git knows which repository to pull changes from. Simply,
it defaults to pull from the repository you `git clone`'d in previous steps.
In Git terminology that default repository is given two names:
it defaults to pull from the repository in which you ran `git clone`
previously. In Git terminology that default repository is given two names:
- The URL for the default upstream repository is called the `origin`.
@ -362,7 +362,7 @@ $ git log master.. --oneline --decorate=no
```
> **Note:** The `git log` command compares your current branch (`fix-doc-bugs`)
> with the `master` branch and lists all the commmits, one per line.
> with the `master` branch and lists all the commits, one per line.
Since all four commits are related to *the same change* to fix spelling mistakes
and break long lines up into shorter lines, it makes sense to combine all four
@ -427,9 +427,8 @@ Taking each step in turn:
```
- In your editor, read the comments at the bottom of the screen. Next, without
modifying the first line (`pick 2e335ac docs: Fix typos and fold long
lines`), change the "`pick`" at the start of all the other lines to
"`squash`".
modifying the first line (`pick 2e335ac docs: Fix typos and fold long lines`),
change the "`pick`" at the start of all the other lines to "`squash`".
As an example, your editor window could appear as follows:
@ -445,7 +444,7 @@ Taking each step in turn:
will see all the commit *messages*. These messages are descriptions for all the
commits you created. At this point you can modify the file as you wish. Once
you save and exit the editor, Git uses whatever is left in the file as the
commit message for your "squashed' commit.
commit message for your "squashed" commit.
If you followed the example [first PR](#first-pr-example),
your first commit ("`2e335ac docs: Fix typos and fold long lines`")
@ -497,14 +496,14 @@ Then, the team is notified and able to re-review your PR more quickly.
Kata Containers CI systems have two methods that allow marking
PRs to prevent them being merged. The methods are
[GibHub labels](https://help.github.com/articles/about-labels/)
[GitHub labels](https://help.github.com/articles/about-labels/)
or keywords in the PR subject line. The keywords can appear anywhere
in the subject line.
The following table summarises some common scenarios and appropriate use
of labels or keywords:
| Scenario | github label | PR description contains |
| Scenario | GitHub label | PR description contains |
| -------- | ------------ | ----------------------- |
| PR created "as an idea" and feedback sought | `rfc` | RFC |
| PR incomplete - needs more work or rework | `do-not-merge` `wip` | WIP |
@ -515,8 +514,8 @@ of labels or keywords:
If any of the values in the table above are set on a PR, it will be
automatically blocked from merging.
> **Note:** Often during dicsussions the abbreviated and full terms are
> used interchangably. For instance, often `DNM` is used
> **Note:** Often during discussions the abbreviated and full terms are
> used interchangeably. For instance, often `DNM` is used
> in discussions as shorthand for `do-not-merge`. The CI systems only
> recognise the above phrases as shown.
@ -648,7 +647,7 @@ For additional information on using the `dep` tool, see
### Stable branch backports
Kata Containers maintains a number of stable branch releases. Bug fixes to the
master branch are selectively applied to (or 'backported') these stable branches.
master branch are selectively applied to (or "backported") these stable branches.
In order to aid identification of commits that potentially should be backported to
the stable branches, all PRs submitted must be labelled with one or more of the
@ -726,7 +725,7 @@ A PR can contain multiple patches. These patches should generally be related to
### Verification
Correct formatting of the PR patches is verified using the
[checkcommits](https://github.com/kata-containers/tests/tree/master/cmd/checkcommits)
[`checkcommits`](https://github.com/kata-containers/tests/tree/master/cmd/checkcommits)
tool.
### Examples
@ -772,8 +771,8 @@ See the [PR review guide](PR-Review-Guide.md) for tips on performing a careful r
We use the GitHub [Required Reviews](https://help.github.com/articles/approving-a-pull-request-with-required-reviews/)
system for reviewers to note if they agree or disagree with a PR. To have
an acknowledgement or 'nack' registered with github, you **must** use the
github 'Review changes' dialog to leave feedback. Notes left only in the
an acknowledgement or "nack" registered with GitHub, you **must** use the
GitHub "Review changes" dialog to leave feedback. Notes left only in the
comments fields, whilst sometimes useful, will not get registered
in the acknowledgement counting system.
@ -783,7 +782,7 @@ Documentation PRs can sometimes use a modified process explained in the
### Review Examples
The following is an example of a valid "ack", as long as
the 'Approve' box is ticked in the Review changes dialog:
the "Approve" box is ticked in the Review changes dialog:
```
Excellent work - thanks for your contribution.
@ -806,7 +805,7 @@ Some of the checks are:
- Functional tests.
- Integretation tests.
The travis job will be executed right after the PR is opened, while the Jenkins
The Travis job will be executed right after the PR is opened, while the Jenkins
jobs will wait to be triggered. A maintainer must add a `/test` comment
on the PR to let the CI jobs run.
@ -824,8 +823,8 @@ rejecting any PR. Although [anyone can review PRs](#reviews), only the
acknowledgement (or "ack") from an Approver counts towards the approval of a PR.
Approvers are listed in GitHub teams, one for each repository. The project
uses the [Pull Approve](https://pullapprove.com) service meaning each
repository contains a top level `.pullapprove.yml` configuration file. This
uses the [Pull Approve](https://PullApprove.com) service meaning each
repository contains a top level `.PullApprove.yml` configuration file. This
file lists the GitHub team used for that repository's approvals.
Each repository can have custom review requirements but the minimum approval
@ -836,7 +835,7 @@ requirements are:
- One [documentation team](https://github.com/orgs/kata-containers/teams/documentation/members)
approval if the PR modifies documentation.
See the `.pullapprove.yml` configuration files for full details.
See the `.PullApprove.yml` configuration files for full details.
## Issue tracking

6
Documentation-Review-Process.md
View File

@ -34,10 +34,10 @@ The following GitHub team lists the users who are members of the Documentation T
## Default document review process
[Project maintainers](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#project-maintainers)
have the power to approve or reject PRs using the pullapprove tool employed by
have the power to approve or reject PRs using the PullApprove tool employed by
all repositories.
If a Documentation Team review is required, the pullapprove configuration will
If a Documentation Team review is required, the PullApprove configuration will
apply and the PR will be blocked until the required number of acks are
obtained for the documentation changes.
@ -154,7 +154,7 @@ PTAL @kata-containers/documentation
1. Request a project maintainer force-merges the PR.
This operation bypasses the pullapprove check that normally stops a PR from
This operation bypasses the PullApprove check that normally stops a PR from
landing until the Documentation Team ack the PR.
1. The maintainer should notify the Documentation Team out of courtesy that

10
README.md
View File

@ -20,7 +20,7 @@ Kata Containers is an open source project and community working to build a stand
The Kata Containers project will initially comprise six components, including the Agent, Runtime, Proxy, Shim, Kernel and packaging of QEMU 2.9. It is designed to be architecture agnostic, run on multiple hypervisors and be compatible with the OCI specification for Docker containers and CRI-O for Kubernetes.
Kata Containers combines technology from [Intel® Clear Containers](https://github.com/clearcontainers/runtime) and [Hyper runV](https://github.com/hyperhq/runv). The code is hosted on Github under the Apache 2 license and the project is managed by the OpenStack Foundation. To learn more about the project and organizations backing the launch, visit https://www.katacontainers.io.
Kata Containers combines technology from [Intel® Clear Containers](https://github.com/clearcontainers/runtime) and [Hyper runV](https://github.com/hyperhq/runv). The code is hosted on GitHub under the Apache 2 license and the project is managed by the OpenStack Foundation. To learn more about the project and organizations backing the launch, visit https://www.katacontainers.io.
# Community
@ -53,7 +53,7 @@ See the [contributing guide](CONTRIBUTING.md) for details on how to contribute t
# Governance
The Kata Containers project is governed according to the [“four opens"](https://governance.openstack.org/tc/reference/opens.html), which are open source, open design, open development, and open community. Technical decisions are made by technical contributors and a representative Architecture Committee. The community is committed to diversity, openness, and encouraging new contributors and leaders to rise up.
The Kata Containers project is governed according to the ["four opens"](https://governance.openstack.org/tc/reference/opens.html), which are open source, open design, open development, and open community. Technical decisions are made by technical contributors and a representative Architecture Committee. The community is committed to diversity, openness, and encouraging new contributors and leaders to rise up.
## Developers
@ -61,11 +61,11 @@ For code contributors, there are currently two roles relevant to project governa
### Contributor
A Contributor to the Kata Containers project is someone who has had code merged within the last 12 months. Contributors are eligible to vote in the Architecture Committee elections. Contributors have read only access to the Kata Containers repos on Github.
A Contributor to the Kata Containers project is someone who has had code merged within the last 12 months. Contributors are eligible to vote in the Architecture Committee elections. Contributors have read only access to the Kata Containers repos on GitHub.
### Maintainer
A Maintainer has the ability to merge code into the Kata Containers project. Maintainers are active Contributors and participants in the projects. In order to become a Maintainer, you must be nominated and approved by the established Maintainers. Maintainers have write access to the Kata Containers repos on Github.
A Maintainer has the ability to merge code into the Kata Containers project. Maintainers are active Contributors and participants in the projects. In order to become a Maintainer, you must be nominated and approved by the established Maintainers. Maintainers have write access to the Kata Containers repos on GitHub.
## Architecture Committee
@ -96,7 +96,7 @@ Vulnerability Management Team (VMT). Vulnerabilities are managed using a
[responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure) model.
Details of how to report a vulnerability, the process and procedures
used for vulnerability management, and responsibilites of the VMT members
used for vulnerability management, and responsibilities of the VMT members
can be found in the [VMT documentation](VMT/VMT.md).
Previous Kata Containers Security Advisories are [listed on their own page](VMT/KCSA.md).

10
VENDORING.md
View File

@ -1,7 +1,7 @@
# Performing vendoring for the Kata Containers project
* [Vendoring tool](#vendoring-tool)
* [How to install and update dep](#how-to-install-and-update-dep)
* [How to install and update `dep`](#how-to-install-and-update-dep)
* [Overview of the main commands](#overview-of-the-main-commands)
* [Vendoring use cases](#vendoring-use-cases)
* [Initialize vendoring of the package](#initialize-vendoring-of-the-package)
@ -9,7 +9,7 @@
* [Update a vendored package](#update-a-vendored-package)
* [Remove a vendored package](#remove-a-vendored-package)
* [Test a pending pull request](#test-a-pending-pull-request)
* [Miscellaneaous](#miscellaneaous)
* [Miscellaneous](#miscellaneous)
## Vendoring tool
@ -18,9 +18,9 @@ project because it is simple and powerful for some corner cases. Furthermore,
this tool is expected to be the official vendoring tool for Golang.
Ensure you use the latest version of the `dep` tool. See
[How to install and update dep](#how-to-install-and-update-dep) for details.
[How to install and update `dep`](#how-to-install-and-update-dep) for details.
### How to install and update dep
### How to install and update `dep`
Install or update this tool using the following command:
```bash
@ -241,7 +241,7 @@ development branch called `work-dev`. In this case you will need to modify
The previous case is more common because typically you do not have permissions
to push directly to the main repository.
## Miscellaneaous
## Miscellaneous
For additional information about vendoring, see
"[Re-vendor PRs](https://github.com/kata-containers/community/blob/master/CONTRIBUTING.md#re-vendor-prs)".

14
VMT/KCSA/KCSA-CVE-2019-5736.md
View File

@ -2,13 +2,13 @@ announcement-date: 2019-02-22
id: KCSA-CVE-2019-5736
title: CVE-2019-5736 'runc container breakout' assessment
title: CVE-2019-5736 "runc container breakout" assessment
description: Impact of CVE-2019-5736 on Kata Containers
potentially-affected-components:
- components: kata-agent
- components: `kata-agent`
version: all
vulnerabilities:
@ -21,7 +21,7 @@ reporters:
affiliation: VMT member
reported:
- Original report seen on dev@opencontainers.org
- oss-sec posting: https://seclists.org/oss-sec/2019/q1/119
- `oss-sec` posting: https://seclists.org/oss-sec/2019/q1/119
- MITRE: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736
issues:
@ -37,13 +37,13 @@ reproduce:
notes:
- The CVE-2019-5736 does not affect Kata Containers. Kata Containers does use the
runc libcontainer library as part of its 'kata-agent' to launch container workloads, but
the kata-agent executable is a permanently running application within the Kata Containers
runc libcontainer library as part of its `kata-agent` to launch container workloads, but
the `kata-agent` executable is a permanently running application within the Kata Containers
VM. Thus, the exit/re-execute cycle utilised by CVE-2019-5736 to execute the injected code
is never undertaken.
- It should be noted, if the exploit had escaped from the kata-agent, the exploit code
- It should be noted, if the exploit had escaped from the `kata-agent`, the exploit code
would have been executing inside the Kata Containers VM as root, and would not have direct
access to either the host system or other container/pods.
- It is highly likely Kata Containers will vendor in and adopt all relevant libcontainer updates
and changes, but given the 'copying' nature of some fixes, a performance and resource impact
and changes, but given the "copying" nature of some fixes, a performance and resource impact
review will be undertaken.

10
VMT/VMT.md
View File

@ -36,7 +36,7 @@ Here are the steps followed.
## Reception
A report is received via the [Kata Containers Launchpad](https://launchpad.net/katacontainers.io). New reports should be created as a 'Private Bug', thus initially restricting visibility
A report is received via the [Kata Containers Launchpad](https://launchpad.net/katacontainers.io). New reports should be created as a "Private Bug", thus initially restricting visibility
to the VMT members and the reporter.
The first steps performed by the VMT are:
@ -57,7 +57,7 @@ The specifics are indexed in the [report taxonomy](#incident-report-taxonomy) an
## Patch development
For a private report, the reporter and the affected projects' core security review teams, plus anyone they deem necessary to develop and validate a fix, are added to the Launchpad bug subscription list.
For a private report, the reporter and the affected project's core security review teams, plus anyone they deem necessary to develop and validate a fix, are added to the Launchpad bug subscription list.
A fix is proposed as a patch to the current master branch (as well as any affected supported branches) and attached to the Launchpad bug, **not sent to the public code review system**.
For public reports, there is no need to directly subscribe anyone and patches can be submitted directly to the code review system instead as Pull Requests (PR).
@ -132,7 +132,7 @@ Once more, fill in the *security code* at the bottom of the page and *submit req
## Publish KCSA
Shortly after pushing the patches (potentially waiting for the first test runs to complete), publish the advisory to the [Kata Containers Dev ML](mailto:kata-dev@lists.katacontainers.io) and slack channels, and add the issue to the [list of KCSA's](KCSA.md).
Shortly after pushing the patches (potentially waiting for the first test runs to complete), publish the advisory to the [Kata Containers development mailing list](mailto:kata-dev@lists.katacontainers.io) and slack channels, and add the issue to the [list of KCSA's](KCSA.md).
Wait until all patches are merged to supported branches before setting the KCSA Issue status to *Fix released*.
## All patches merged
@ -191,7 +191,7 @@ Issues that take too much time to be fixed (e.g., more than 2 weeks) or Issues t
Whenever such a case occurs, the Kata Containers [Architecture Committee](https://github.com/kata-containers/community#architecture-committee) is subscribed to the Launchpad bug in order to discuss whether or not it's imperative to keep that particular bug private.
The same process is followed if an embargoed issue is, accidentally or not, leaked to the public. In all likelyhood that Issue will then be moved to the Public state.
The same process is followed if an embargoed issue is, accidentally or not, leaked to the public. In all likelihood that Issue will then be moved to the Public state.
## Downstream stakeholders
@ -199,7 +199,7 @@ Kata Containers as an upstream project is used in a number of distributions, pro
In the spirit of [responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure), this ecosystem, collectively known as the downstream stakeholders, needs to be warned in advance to be able to prepare patches and roll them out in a coordinated fashion on disclosure day.
The embargo period is kept voluntarily small (3-5 business days), as a middle ground between keeping the vulnerability under cover for too long and not giving a chance to downstream stakeholders to react.
If you are currently not a referenced stakeholder and think you should definitely be included on that email distribution list, please submit a [Launchpad bug](https://launchpad.net/katacontainers.io) with a rationale for your additon.
If you are currently not a referenced stakeholder and think you should definitely be included on that email distribution list, please submit a [Launchpad bug](https://launchpad.net/katacontainers.io) with a rationale for your addition.
# Templates

2
VMT/templates/KCSA.md
View File

@ -52,7 +52,7 @@ notes:
```
Once approved, the request will be added to the documentation repo and linked from the KCSA index page. It will then be emailed out.
We send two separate emails, to avoid off-topic replies to oss-security list:
We send two separate emails, to avoid off-topic replies to `oss-security` list:
```
- To: <kata-dev@lists.katacontainers.io>

2
VMT/templates/KCSN.md
View File

@ -23,6 +23,6 @@ example snippets of configuration files should be included here.
### Contacts / References ###
Author: <author name(s) and company(s)>
This KCSN : <link to KCSN on documents repo>
Original LaunchPad Bug : <link to launchpad bug for affected project/service>
Original Launchpad Bug : <link to launchpad bug for affected project/service>
Mailing List : [Security] tag on kata-dev@lists.katacontainers.io
CVE: <CVE number if one was filed>

2
VMT/templates/downstream-stakeholder-notification.md
View File

@ -1,6 +1,6 @@
# Downstream stakeholders notification email (private issues) template
We send two separate emails, to avoid off-topic replies to linux-distros:
We send two separate emails, to avoid off-topic replies to Linux-distros:
```
- To: <embargo-notice@lists.katacontainers.io>