github/linuxkit
1
0
Fork 0
mirror of https://github.com/linuxkit/linuxkit.git synced 2025-11-04 14:40:14 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #1498 from thaJeztah/add-open-source-boilerplating

Browse Source 
Add license, templates, and other files for open sourcing
This commit is contained in:
Justin Cormack
2017-04-17 11:13:47 -05:00
committed by GitHub
parent 8148701099 6d1ea86da6
commit 88e9c24c62
9 changed files with 918 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
.github/ISSUE_TEMPLATE.md vendored Normal file
View File

@@ -0,0 +1,38 @@
<!--
If you are reporting a new issue, make sure that we do not have any duplicates
already open. You can ensure this by searching the issue list for this
repository. If there is a duplicate, please close your issue and add a comment
to the existing issue instead.
If you suspect your issue is a bug, please edit your issue description to
include the BUG REPORT INFORMATION shown below. If you fail to provide this
information within 7 days, we cannot debug your issue and will close it. We
will, however, reopen it if you later provide the information.
For more information about reporting issues, see
https://github.com/docker/linuxkit/blob/master/CONTRIBUTING.md#reporting-other-issues
---------------------------------------------------
BUG REPORT INFORMATION
---------------------------------------------------
Use the commands below to provide key information from your environment:
You do NOT have to include this information if this is a FEATURE REQUEST
-->
**Description**
<!--
Briefly describe the problem you are having in a few paragraphs.
-->
**Steps to reproduce the issue:**
**Describe the results you received:**
**Describe the results you expected:**
**Additional information you deem important (e.g. issue happens only occasionally):**

29
.github/PULL_REQUEST_TEMPLATE.md vendored Normal file
View File

@@ -0,0 +1,29 @@
<!--
Please make sure you've read and understood our contributing guidelines;
https://github.com/docker/linuxkit/blob/master/CONTRIBUTING.md
** Make sure all your commits include a signature generated with `git commit -s` **
For additional information on our contributing process, read our contributing
guide https://docs.docker.com/opensource/code/
If this is a bug fix, make sure your description includes "fixes #xxxx", or
"closes #xxxx"
Please provide the following information:
-->
**- What I did**
**- How I did it**
**- How to verify it**
**- Description for the changelog**
<!--
Write a short (one line) summary that describes the changes in this
pull request for inclusion in the changelog:
-->
**- A picture of a cute animal (not mandatory but encouraged)**

263
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,263 @@
# Contributing to LinuxKit
Want to hack on this project? Awesome! Here are instructions to get you started.
Additional information can be found in the docs:
[issue triage](https://github.com/docker/linuxkit/blob/master/docs/issue-triage.md),
and [review process](https://github.com/docker/linuxkit/blob/master/docs/reviewing.md).
## Reporting security issues
The LinuxKit maintainers take security seriously. If you discover a security
issue, please bring it to their attention right away!
Please **DO NOT** file a public issue, instead send your report privately to
[security@docker.com](mailto:security@docker.com).
Security reports are greatly appreciated and we will publicly thank you for it.
We also like to send gifts&mdash;if you're into Docker schwag, make sure to let
us know. We currently do not offer a paid security bounty program, but are not
ruling it out in the future.
## Reporting other issues
A great way to contribute to the project is to send a detailed report when you
encounter an issue. We always appreciate a well-written, thorough bug report,
and will thank you for it!
Check that [our issue database](https://github.com/docker/linuxkit/issues)
doesn't already include that problem or suggestion before submitting an issue.
If you find a match, you can use the "subscribe" button to get notified on
updates. Do *not* leave random "+1" or "I have this too" comments, as they
only clutter the discussion, and don't help resolving it. However, if you
have ways to reproduce the issue or have additional information that may help
resolving the issue, please leave a comment.
Also include the steps required to reproduce the problem if possible and
applicable. This information will help us review and fix your issue faster.
When sending lengthy log-files, consider posting them as a gist (https://gist.github.com).
Don't forget to remove sensitive data from your logfiles before posting (you can
replace those parts with "REDACTED").
## Quick contribution tips and guidelines
This section gives the experienced contributor some tips and guidelines.
### Pull requests are always welcome
Not sure if that typo is worth a pull request? Found a bug and know how to fix
it? Do it! We will appreciate it. Any significant improvement should be
documented as [a GitHub issue](https://github.com/docker/linuxkit/issues) before
anybody starts working on it.
We are always thrilled to receive pull requests. We do our best to process them
quickly. If your pull request is not accepted on the first try, don't get
discouraged! Our contributor's guide explains [the review process we
use for simple changes](https://docs.docker.com/opensource/workflow/make-a-contribution/).
### Design and cleanup proposals
You can propose new designs for existing features. You can also design
entirely new features. We really appreciate contributors who want to refactor or
otherwise cleanup our project. For information on making these types of
contributions, see [the advanced contribution
section](https://docs.docker.com/opensource/workflow/advanced-contributing/) in
the contributors guide.
We try hard to keep LinuxKit lean and focused. LinuxKit can't do everything for
everybody. This means that we might decide against incorporating a new feature.
However, there might be a way to implement that feature *on top of* LinuxKit.
### Commit Messages
Commit messages must start with a capitalized and short summary (max. 50 chars)
written in the imperative, followed by an optional, more detailed explanatory
text which is separated from the summary by an empty line.
Commit messages should follow best practices, including explaining the context
of the problem and how it was solved, including in caveats or follow up changes
required. They should tell the story of the change and provide readers
understanding of what led to it.
If you're lost about what this even means, please see [How to Write a Git
Commit Message](http://chris.beams.io/posts/git-commit/) for a start.
In practice, the best approach to maintaining a nice commit message is to
leverage a `git add -p` and `git commit --amend` to formulate a solid
changeset. This allows one to piece together a change, as information becomes
available.
If you squash a series of commits, don't just submit that. Re-write the commit
message, as if the series of commits was a single stroke of brilliance.
That said, there is no requirement to have a single commit for a PR, as long as
each commit tells the story. For example, if there is a feature that requires a
package, it might make sense to have the package in a separate commit then have
a subsequent commit that uses it.
Remember, you're telling part of the story with the commit message. Don't make
your chapter weird.
### Review
Code review comments may be added to your pull request. Discuss, then make the
suggested modifications and push additional commits to your feature branch. Post
a comment after pushing. New commits show up in the pull request automatically,
but the reviewers are notified only when you comment.
Pull requests must be cleanly rebased on top of master without multiple branches
mixed into the PR.
**Git tip**: If your PR no longer merges cleanly, use `rebase master` in your
feature branch to update your pull request rather than `merge master`.
Before you make a pull request, squash your commits into logical units of work
using `git rebase -i` and `git push -f`. A logical unit of work is a consistent
set of patches that should be reviewed together: for example, upgrading the
version of a vendored dependency and taking advantage of its now available new
feature constitute two separate units of work. Implementing a new function and
calling it in another file constitute a single logical unit of work. The very
high majority of submissions should have a single commit, so if in doubt: squash
down to one.
After every commit, [make sure the test suite passes]
(https://docs.docker.com/opensource/project/test-and-docs/). Include documentation
changes in the same pull request so that a revert would remove all traces of
the feature or fix.
Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in commits that
close an issue. Including references automatically closes the issue on a merge.
### Merge approval
Docker maintainers use LGTM (Looks Good To Me) in comments or GitHub approval
on the code review to indicate acceptance.
A change requires at least one LGTM from a maintainers of each component
affected. A list of maintainers can be found in the [MAINTAINERS](MAINTAINERS)
file.
### Community Guidelines and Code of Conduct
When contributing to this project, we expect you to respect our community
guidelines and [code of conduct](https://github.com/docker/code-of-conduct)
We want to keep the community awesome, growing and collaborative. We need your
help to keep it that way. To help with this we've come up with some general
guidelines for the community as a whole:
* Be nice: Be courteous, respectful and polite to fellow community members:
no regional, racial, gender, or other abuse will be tolerated. We like
nice people way better than mean ones!
* Encourage diversity and participation: Make everyone in our community feel
welcome, regardless of their background and the extent of their
contributions, and do everything possible to encourage participation in
our community.
* Keep it legal: Basically, don't get us in trouble. Share only content that
you own, do not share private or sensitive information, and don't break
the law.
* Stay on topic: Make sure that you are posting to the correct channel and
avoid off-topic discussions. Remember when you update an issue or respond
to an email you are potentially sending to a large number of people. Please
consider this before you update. Also remember that nobody likes spam.
* Don't send email to the maintainers: There's no need to send email to the
maintainers to ask them to investigate an issue or to take a look at a
pull request. Instead of sending an email, GitHub mentions should be
used to ping maintainers to review a pull request, a proposal or an
issue.
### Guideline violations — 3 strikes method
The point of this section is not to find opportunities to punish people, but we
do need a fair way to deal with people who are making our community suck.
1. First occurrence: We'll give you a friendly, but public reminder that the
behavior is inappropriate according to our guidelines.
2. Second occurrence: We will send you a private message with a warning that
any additional violations will result in removal from the community.
3. Third occurrence: Depending on the violation, we may need to delete or ban
your account.
**Notes:**
* Obvious spammers are banned on first occurrence. If we don't do this, we'll
have spam all over the place.
* Violations are forgiven after 6 months of good behavior, and we won't hold a
grudge.
* People who commit minor infractions will get some education, rather than
hammering them in the 3 strikes process.
* The rules apply equally to everyone in the community, no matter how much
you've contributed.
* Extreme violations of a threatening, abusive, destructive or illegal nature
will be addressed immediately and are not subject to 3 strikes or forgiveness.
* Contact abuse@docker.com to report abuse or appeal violations. In the case of
appeals, we know that mistakes happen, and we'll work with you to come up with a
fair solution if there has been a misunderstanding.
### Sign your work
The sign-off is a simple line at the end of the explanation for the patch. Your
signature certifies that you wrote the patch or otherwise have the right to pass
it on as an open-source patch. The rules are pretty simple: if you can certify
the below (from [developercertificate.org](http://developercertificate.org/)):
```
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
```
Then you just add a line to every git commit message:
Signed-off-by: Joe Smith <joe.smith@email.com>
Use your real name (sorry, no pseudonyms or anonymous contributions.)
If you set your `user.name` and `user.email` git configs, you can sign your
commit automatically with `git commit -s`.

191
LICENSE Normal file
View File

@@ -0,0 +1,191 @@
Apache License
Version 2.0, January 2004
https://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Copyright 2015-2017 Docker, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

46
MAINTAINERS Normal file
View File

@@ -0,0 +1,46 @@
# Project maintainers file
#
# This file describes who runs the docker/linuxkit project and how.
# This is a living document - if you see something out of date or missing, speak up!
#
# It is structured to be consumable by both humans and programs.
# To extract its contents programmatically, use any TOML-compliant parser.
#
# This file is compiled into the MAINTAINERS file in docker/opensource.
#
[Org]
[Org."Core maintainers"]
people = [
"ijc25",
"justincormack",
"riyazdf",
"rneugeba",
]
[people]
# A reference list of all people associated with the project.
# All other sections should refer to people by their canonical key
# in the people section.
# ADD YOURSELF HERE IN ALPHABETICAL ORDER
[People.ijc25]
Name = "Ian Campbell"
Email = "ian.campbell@docker.com"
GitHub = "ijc25"
[people.justincormack]
Name = "Justin Cormack"
Email = "justin.cormack@docker.com"
GitHub = "justincormack"
[people.riyazdf]
Name = "Riyaz Faizullabhoy"
Email = "riyaz@docker.com"
GitHub = "riyazdf"
[people.rneugeba]
Name = "Rolf Neugebauer"
Email = "rolf.neugebauer@docker.com"
GitHub = "rneugeba"

13
NOTICE Normal file
View File

@@ -0,0 +1,13 @@
Copyright 2015-2017 Docker, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

2
README.md
View File

@@ -98,3 +98,5 @@ There are weekly [development reports](reports/) summarizing work carried out in
## FAQ
See [FAQ](docs/faq.md).
Released under the [Apache 2.0 license](LICENSE).

117
docs/issue-triage.md Normal file
View File

@@ -0,0 +1,117 @@
Triaging of issues
------------------
Triage provides an important way to contribute to an open source project.
Triage helps ensure issues resolve quickly by:
- Describing the issue's intent and purpose is conveyed precisely. This is
necessary because it can be difficult for an issue to explain how an end user
experiences a problem and what actions they took.
- Giving a contributor the information they need before they commit to
resolving an issue.
- Lowering the issue count by preventing duplicate issues.
- Streamlining the development process by preventing duplicate discussions.
If you don't have time to code, consider helping with triage. The community
will thank you for saving them time by spending some of yours.
### 1. Ensure the issue contains basic information
Before triaging an issue very far, make sure that the issue's author provided
the standard issue information. This will help you make an educated
recommendation on how this to categorize the issue.
If you cannot triage an issue using what its author provided, explain kindly to
the author that they must provide additional information to clarify the problem.
If the author does not respond requested information within the timespan of a
week, close the issue with a kind note stating that the author can request for
the issue to be reopened when the necessary information is provided.
### 2. Classify the Issue
An issue can have multiple of the following labels. Typically, a properly
classified issue should have:
- One label identifying its kind (`kind/*`).
- One or multiple labels identifying the functional areas of interest (`area/*`).
- Where applicable, one label categorizing its difficulty (`exp/*`).
#### Issue kind
| Kind | Description |
|------------------|---------------------------------------------------------------------------------------------------------------------------------|
| kind/bug | Bugs are bugs. The cause may or may not be known at triage time so debugging should be taken account into the time estimate. |
| kind/enhancement | Enhancements are not bugs or new features but can drastically improve usability or performance of a project component. |
| kind/feature | Functionality or other elements that the project does not currently support. Features are new and shiny. |
| kind/question | Contains a user or contributor question requiring a response. |
#### Functional area
| Area |
|---------------------------|
| area/build |
| area/cli |
| area/containerd |
| area/docs |
| area/kernel |
| area/logging |
| area/networking |
| area/security |
| area/testing |
| area/time |
| area/unikernel |
| area/usability |
#### Platform
| Platform |
|---------------------------|
| platform/arm |
| platform/aws |
| platform/azure |
| platform/gcp |
| platform/osx |
| platform/windows |
#### Experience level
Experience level is a way for a contributor to find an issue based on their
skill set. Experience types are applied to the issue or pull request using
labels.
| Level | Experience level guideline |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| exp/beginner | New to LinuxKit, and is looking to help while learning the basics. |
| exp/intermediate | Comfortable with the project and understands the core concepts, and looking to dive deeper into the project. |
| exp/expert | Proficient with the project and has been following, and active in, the community to understand the rationale behind design decisions and where the project is headed. |
As the table states, these labels are meant as guidelines.
#### Triage status
To communicate the triage status with other collaborators, you can apply status
labels to issues. These labels prevent duplicating effort.
| Status | Description |
|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| status/confirmed | You triaged the issue, and were able to reproduce the issue. Always leave a comment how you reproduced, so that the person working on resolving the issue has a way to set up a test-case.
| status/accepted | Apply to enhancements / feature requests that we think are good to have. Adding this label helps contributors find things to work on.
| status/more-info-needed | Apply this to issues that are missing information (e.g. no steps to reproduce), or require feedback from the reporter. If the issue is not updated after a week, it can generally be closed.
| status/needs-attention | Apply this label if an issue (or PR) needs more eyes.
### 3. Prioritizing issue
When, and only when, an issue is attached to a specific milestone, the issue can be labeled with the
following labels to indicate their degree of priority (from more urgent to less urgent).
| Priority | Description |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------|
| priority/P0 | Urgent: Security, critical bugs, blocking issues. P0 basically means drop everything you are doing until this issue is addressed. |
| priority/P1 | Important: P1 issues are a top priority and a must-have for the next release. |
| priority/P2 | Normal priority: default priority applied. |
| priority/P3 | Best effort: those are nice to have / minor issues. |
And that's it. That should be all the information required for a new or
existing contributor to come in a resolve an issue.

219
docs/reviewing.md Normal file
View File

@@ -0,0 +1,219 @@
# Pull request reviewing process
## Labels
Labels are carefully picked to optimize for:
- Readability: maintainers must immediately know the state of a PR
- Filtering simplicity: different labels represent many different aspects of
the reviewing work, and can even be targeted at different maintainers groups.
A pull request should only be attributed labels documented in this section: other labels that may
exist on the repository should apply to issues.
### DCO labels
* `dco/no`: automatically set by a bot when one of the commits lacks proper signature
### Status labels
* `status/0-triage`
* `status/1-design-review`
* `status/2-code-review`
* `status/3-docs-review`
* `status/4-merge`
Special status labels:
* `status/failing-ci`: indicates that the PR in its current state fails the test suite
* `status/needs-attention`: calls for a collective discussion during a review session
### Impact labels (apply to merged pull requests)
* `impact/api`
* `impact/changelog`
* `impact/cli`
* `impact/deprecation`
### Process labels (apply to merged pull requests)
Process labels are to assist in preparing (patch) releases. These labels should only be used for pull requests.
Label | Use for
------------------------------- | -------------------------------------------------------------------------
`process/cherry-pick` | PRs that should be cherry-picked in the bump/release branch. These pull-requests must also be assigned to a milestone.
`process/cherry-picked` | PRs that have been cherry-picked. This label is helpful to find PR's that have been added to release-candidates, and to update the change log
`process/docs-cherry-pick` | PRs that should be cherry-picked in the docs branch. Only apply this label for changes that apply to the *current* release, and generic documentation fixes, such as Markdown and spelling fixes.
`process/docs-cherry-picked` | PRs that have been cherry-picked in the docs branch
`process/merge-to-master` | PRs that are opened directly on the bump/release branch, but also need to be merged back to "master"
`process/merged-to-master` | PRs that have been merged back to "master"
## Workflow
An opened pull request can be in 1 of 5 distinct states, for each of which
there is a corresponding label that needs to be applied.
### Triage - `status/0-triage`
Maintainers are expected to triage new incoming pull requests by removing the
`status/0-triage` label and adding the correct labels (e.g.
`status/1-design-review`) before any other interaction with the PR. The
starting label may potentially skip some steps depending on the kind of pull
request: use your best judgement.
Maintainers should perform an initial, high-level, overview of the pull request
before moving it to the next appropriate stage:
- Has DCO
- Contains sufficient justification (e.g., usecases) for the proposed change
- References the Github issue it fixes (if any) in the commit or the first
Github comment
Possible transitions from this state:
* Close: e.g., unresponsive contributor without DCO
* `status/1-design-review`: general case
* `status/2-code-review`: e.g. trivial bugfix
* `status/3-docs-review`: non-proposal documentation-only change
### Design review - `status/1-design-review`
Maintainers are expected to comment on the design of the pull request. Review
of documentation is expected only in the context of design validation, not for
stylistic changes.
Ideally, documentation should reflect the expected behavior of the code. No
code review should take place in this step.
There are no strict rules on the way a design is validated: we usually aim for
a consensus, although a single maintainer approval is often sufficient for
obviously reasonable changes. In general, strong disagreement expressed by any
of the maintainers should not be taken lightly.
Once design is approved, a maintainer should make sure to remove this label and
add the next one.
Possible transitions from this state:
* Close: design rejected
* `status/2-code-review`: general case
* `status/3-docs-review`: proposals with only documentation changes
### Code review - `status/2-code-review`
Maintainers are expected to review the code and ensure that it is good quality
and in accordance with the documentation in the PR.
New testcases are expected to be added. Ideally, those testcases should fail
when the new code is absent, and pass when present. The testcases should strive
to test as many variants, code paths, as possible to ensure maximum coverage.
Changes to code must be reviewed and approved (LGTM'd) by a minimum of one code
maintainer. When the author of a PR is a maintainer, he still needs the
approval of one other maintainer.
Once code is approved according to the rules of the subsystem, a maintainer
should make sure to remove this label and add the next one. If documentation is
absent but expected, maintainers should ask for documentation and move to
status `status/3-docs-review` for docs maintainer to follow.
Possible transitions from this state:
* Close
* `status/1-design-review`: new design concerns are raised
* `status/3-docs-review`: general case
* `status/4-ready-to-merge`: change not impacting documentation
### Docs review - `status/3-docs-review`
Maintainers are expected to review the documentation in its bigger context,
ensuring consistency, completeness, validity, and breadth of coverage across
all existing and new documentation.
They should ask for any editorial change that makes the documentation more
consistent and easier to understand.
The docker/docker repository only contains _reference documentation_, all
"narrative" documentation is kept in a [unified documentation
repository](https://github.com/docker/docker.github.io). Reviewers must
therefore verify which parts of the documentation need to be updated. Any
contribution that may require changing the narrative should get the
`impact/documentation` label: this is the signal for documentation maintainers
that a change will likely need to happen on the unified documentation
repository. When in doubt, it’s better to add the label and leave it to
documentation maintainers to decide whether it’s ok to skip. In all cases,
leave a comment to explain what documentation changes you think might be needed.
- If the pull request does not impact the documentation at all, the docs review
step is skipped, and the pull request is ready to merge.
- If the changes in the pull request require changes to the documentation,
those changes must be included as part of the pull request and will be
reviewed now.
Once documentation is approved, a maintainer should make sure to remove this
label and add the next one.
Possible transitions from this state:
* Close
* `status/1-design-review`: new design concerns are raised
* `status/2-code-review`: requires more code changes
* `status/4-ready-to-merge`: general case
### Merge - `status/4-ready-to-merge`
Maintainers are expected to merge this pull request as soon as possible. They
can ask for a rebase or carry the pull request themselves.
Possible transitions from this state:
* Merge: general case
* Close: carry PR
After merging a pull request, the maintainer should consider applying one or
multiple impact labels to ease future classification:
* `impact/api` signifies the patch impacted the Engine API
* `impact/changelog` signifies the change is significant enough to make it in
the changelog
* `impact/cli` signifies the patch impacted a CLI command
* `impact/deprecation` signifies the patch participates in deprecating an
existing feature
### Close
If a pull request is closed it is expected that sufficient justification will
be provided. In particular, if there are alternative ways of achieving the same
net result then those needs to be spelled out. If the pull request is trying to
solve a use case that is not one that we (as a community) want to support then
a justification for why should be provided.
The number of maintainers it takes to decide and close a PR is deliberately
left unspecified. We assume that the group of maintainers is bound by mutual
trust and respect, and that opposition from any single maintainer should be
taken into consideration. Similarly, we expect maintainers to justify their
reasoning and to accept debating.
## Escalation process
Despite the previously described reviewing process, some PR might not show any
progress for various reasons:
- No strong opinion for or against the proposed patch
- Debates about the proper way to solve the problem at hand
- Lack of consensus
- ...
All these will eventually lead to stalled PR, where no apparent progress is
made across several weeks, or even months.
Maintainers should use their best judgement and apply the
`status/needs-attention` label. It must be used sparingly, as each PR with such
label will be discussed by a group of maintainers during a review session. The
goal of that session is to agree on one of the following outcomes for the PR:
* Close, explaining the rationale for not pursuing further
* Continue, either by pushing the PR further in the workflow, or by deciding
to carry the patch (ideally, a maintainer should be immediately assigned to
make sure that the PR keeps continued attention)