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

add license, and files for opensourcing

Browse Source 
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn
2017-04-05 13:28:21 +02:00
parent 0fe2714486
commit 6d1ea86da6
9 changed files with 918 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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)