kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Contributing instructions for sig-cli

This commit is contained in:
Phillip Wittrock 2017-01-27 11:43:03 -08:00
parent b5b68943d2
commit 0f4843b97d
3 changed files with 347 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
contributors/design-proposals/sig-cli/template.md Normal file
View File

@ -0,0 +1,38 @@
# <Title>
Status: Pending
Version: Alpha | Beta | GA
Assignee: <github handle>
## Motivation
<2-6 sentences about why this is needed>
## Proposal
<4-6 description of the proposed solution>
## User Experience
### Use Cases
<enumerated list of use cases for this feature>
<in depth description of user experience>
<*include full examples*>
## Implementation
<in depth description of how the feature will be implemented. in some cases this may be very simple.>
### Client/Server Backwards/Forwards compatibility
<define behavior when using a kubectl client with an older or newer version of the apiserver (+-1 version)>
## Alternatives considered
<short description of alternative solutions to be considered>

26
sig-cli/README.md
View File

@ -14,6 +14,30 @@ We focus on the development and standardization of the CLI [framework](https://g
* Google Group: <https://groups.google.com/forum/#!forum/kubernetes-sig-cli>
## Organizers:
**Note:** Escalate to these folks if you cannot get help from slack or the Google group
* Fabiano Franz <ffranz@redhat.com>, Red Hat
- slack / github: @fabianofranz
* Phillip Wittrock <pwittroc@google.com>, Google
* Tony Ado <coolhzb@gmail.com>, Alibaba
- slack / github: @pwittrock
* Tony Ado <coolhzb@gmail.com>, Alibaba
- slack / github: @adohe
## Contributing
See [this document](https://github.com/kubernetes/community/blob/master/sig-cli/contributing.md) for contributing instructions.
## Sig-cli teams
Mention one or more of
| Name | Description |
|------------------------------------|--------------------------------------------------|
|@kubernetes/sig-cli-bugs | For bugs in kubectl |
|@kubernetes/sig-cli-feature-requests| For initial discussion of new feature requests |
|@kubernetes/sig-cli-proposals | For in depth discussion of new feature proposals |
|@kubernetes/sig-cli-pr-reviews | For PR code reviews |
|@kubernetes/sig-test-failures | For e2e test flakes |
|@kubernetes/sig-cli-misc | For general discussion and escalation |

284
sig-cli/contributing.md Normal file
View File

@ -0,0 +1,284 @@
# Contributing to sig-Cli
This document explains the process for contributing code to the kubernetes
repo through the sig-cli community.
## TL;DR
- New contributors should reach out on slack sig-cli - [link](https://github.com/kubernetes/community/tree/master/sig-cli) for an issue to work on that has an approved design
- New contributors should attend the next sig-cli meeting and introduce themselves
- Write tests
## Important
The [sig-cli community page](https://github.com/kubernetes/community/tree/master/sig-cli)
contains the GitHub handles for the sig-cli leads, slack channels,
email discussion group, and bi-weekly meeting time.
## Message to new contributors
Welcome to the Kubernetes sig-cli contributing guide. We are excited
about the prospect of you joining our community. Please understand
that all contributions to Kubernetes require time and commitment from
the project maintainers to review the ux, software design, and code. We
recommend that you reach out to one of the sig leads
and ask the best way to get started. It is likely that there a couple
issues perfect for a new contributor to get started on.
sig leads can be reached in the sig-cli slack channel or at the sig-cli
bi-weekly meeting. See the [sig-cli community page](https://github.com/kubernetes/community/tree/master/sig-cli)
for a link to the slack channel, list of sig leads, and the community meeting time and location.
Example message for asking how to become a contributor:
Hello, my name is <your name>. I would like to get involved in
contributing to the Kubernetes project. What is the best way to
get started?
Please understand that mentoring and on boarding new contributors takes
a lot time and energy from maintainers who have many other
responsibilities.
## Before you begin
- Visit the [sig-cli community page](https://github.com/kubernetes/community/tree/master/sig-cli)
- Join the `kubernetes-sig-cli@googlegroups.com` so you get email updates
- Join the Kubernetes slack channel `sig-cli`
- Introduce yourself to the community by sending an email to kubernetes-sig-cli@googlegroups.com and let us know you want to be a contributor
## Finding an existing issue to work on
The preferred way to own a piece of work is to directly reach out
to one of the sig-cli leads. This will ensure that the issue is
high-priority enough that it will receive PR review bandwidth from
the sig-cli community.
1. In the Kubernetes sig-cli slack channel, mention @pwittrock, @adohe, or @fabianofranz and ask if there are any issues you could pick up
2. Attend the sig-cli [bi-weekly meeting](https://github.com/kubernetes/community/tree/master/sig-cli).
- Introduce yourself at the beginning of the meeting
## Life of a sig-cli bug overview
1. File a GitHub issue
- Mention `@kubernetes/sig-cli-bugs`
- Describe steps to reproduce the issue including client / server version
2. Implement the fix
- Send a PR
- Add `Closes #<Issue Number>` to the description
- Mention `@kubernetes/sig-cli-pr-reviews` in a comment
- Incorporate review feedback
- **Note:** Include unit and e2e tests
7. Release
- Wait for your feature to appear in the next Kubernetes release!
## Life of a sig-cli feature overview
Picking up an issue and implementing it without getting approval for
the user experience and software design often results in wasted time
and effort due to decisions such as flag-names, command names, specific
command behavior.
In order to minimize wasted work and improve communication across efforts,
the user experience and software design must be agreed upon before
any PRs are sent for code review.
1. Identify a problem - GitHub issue with basic description
2. Propose a solution - GitHub design proposal PR
- **Action:** Write a design proposal using the [template](contributors/design-proposals/sig-cli/template.md). Once
complete, create a pull request and mention `@kubernetes/sig-cli-misc`
- Avoid "Work In Progress" PRs (WIP), only send the PR after you
consider it complete. To get early feedback, consider messaging the
email discussion group.
- Expect feedback from 2-3 different sig-cli community members in the form of PR comments
- Incorporate feedback from sig-cli community members and comment "PTAL" (please take another look)
- Proposal accepted by at least one sig-cli lead
- Proposal merged
3. Communicate what will be done - Discussion at sig-cli bi-weekly meeting - See the [sig-cli community page](https://github.com/kubernetes/community/tree/master/sig-cli) for meeting time and location.
- **Note:** This should be done *before* the proposal has been merged, and after an initial round of feedback - e.g. several folks have looked at it and left commends.
- **Action:** Add the design proposal as an item to the [bi-weekly meeting agenda](https://docs.google.com/document/d/1r0YElcXt6G5mOWxwZiXgGu_X6he3F--wKwg-9UBc29I/edit)
- Make sure the sig-cli community is aware of the work that is being done and can comment on it
- Should be included in meeting notes sent to the sig-cli googlegroup
4. Add feature to Kubernetes release feature repo in [kubernetes/features](https://github.com/kubernetes/features/)
- **Action:** *Done by sig-cli lead* - add the feature to the feature tracking repo tag
to a release. This is done to ensure release related decisions are
properly made and communicated. Such as defining alpha / beta / ga
release, proper testing, and documentation are completed.
5. Implement the code - GitHub implementation PR
- **Action:** Implement the solution described in the proposal, then
send a PR - **include a link to the design proposal in the description**
- Incorporate review feedback
- **Note:** Include unit and e2e tests
6. Update related documentation
- [Concept Docs](https://github.com/kubernetes/kubernetes.github.io/tree/master/docs/concepts/tools/kubectl)
- [Tasks Docs](https://github.com/kubernetes/kubernetes.github.io/tree/master/docs/tasks/tools/kubectl)
7. Release
- Wait for your feature to appear in the next Kubernetes release!
# New feature development
## Creating a GitHub issue
**Note:** For new contributors, it is recommended that you pick up an
existing issue with an approved design proposal by reaching out a sig-lead.
See the [Message to new contributors](#message-to-new-contributors).
In order to start a discussion around a feature, create a new GitHub issue
in the https://github.com/kubernetes/kubernetes repo and mention `@kubernetes/sig-cli-misc`.
Keep the issue to 2-4 sentence description of the basic description of
the problem and proposed solution.
**Note:** You must mention `@kubernetes/sig-cli-feature-requests` in the description of the
issue or in a comment for someone from the sig-cli community to look
at the issue.
## Creating a design proposal
**Note:** For new contributors, it is recommended that you pick up an
existing issue with an approved design proposal by reaching out to a sig-lead.
See the [Message to new contributors](#message-to-new-contributors).
Once at least one sig-lead has agreed that design and code review resources
can be allocated to tackle a particular issue, the fine details
of the user experience and design should be agreed upon.
A PR is filed against the https://github.com/kubernetes/community repo.
This will provide a chance for community members to comment on the
user experience and software design.
**Note:** This step is important to prevent a lot of code churn and
thrashing around issues like flag names, command names, etc.
**Note:** It is normal for sig-cli community members to push back on
feature requests and proposals. sig-cli development and review resources are extremely constrained.
If your proposal is not high-impact or urgent it may not be accepted
in favor of more pressing needs. sig-cli community members should
be free to say: "No, not this release." or "No, not this year." or "No, not right now because although this
is desirable we need help on these other concrete issues before we can
tackle this." or "No, this problem should be solved in another way."
Create a design proposal PR under
https://github.com/kubernetes/community/tree/master/contributors/design-proposals/sig-cli/
by copying template.md.
Mention `@kubernetes/sig-cli-proposals` on the proposal and link to
the proposal from the original issue. Expect to get feedback
from 2-3 community members. At least
one sig-lead must approve the design proposal for it to be accepted.
## Discussing at sig-cli
Finally, when a contributor picks up a design proposals and is ready
to begin implementing it, we should put it as an item on the next
sig-cli agenda. This ensures that everyone in sig-cli community
is aware that work is being started.
## Updating the feature repo
The kubernetes/feature repo exists to help PMs, folks managing the release,
and sig leads coordinate the work going into a given release. This
includes items like:
- ensuring all items slated for the release have been completed, or have
been disabled and pushed into the next release.
- support level for items has been properly defined - alpha / beta / ga
- api changes have been properly vetted by the appropriate parties
- user facing documentation has been updated
**Note:** in most cases this will be done by sig leads on behalf of the
other community members.
## Implementing the feature
Contributors can begin implementing a feature before any of the above
steps have been completed, but should not send a PR until
the design proposal has been approved / merged.
Go [here](contributors/devel/development.md)
for instructions on setting up the Kubernetes development environment.
**Note:** All new features must have automated tests in the same PR.
Small features and flag changes require only unit/integration tests,
while larger changes require both unit/integration tests and e2e tests.
If you get stuck or need help, reach out in the Kubernetes slack
channel and mention @jess and @adohe.
## Updating documentation
Most new features should include user facing documentation. This is
important to make sure that users are aware of the cool new thing that
was added. Depending on the contributor and size of the feature, this
may be done either by the same contributor that implemented the feature,
or another contributor who is more familiar with the existing docs.
## Notes on release
4 weeks before a Kubernetes release, development enters a stabilization
period where no new features are merged. For a feature to be accepted
into a release, it must be fully merged and tested by this time.
# Escalation
## What to do if your bug issue is stuck
If an issue isn't getting any attention and is unresolved, mention
@kubernetes/sig-cli-fea or @kubernetes/sig-cli-bugs.
Highly the severity and urgency of the issue. For severe issues
escalate by contacting sig leads and attending the bi-weekly sig-cli
meeting.
## What to do if your feature request issue is stuck
If an issue isn't getting any attention and is unresolved, mention
@kubernetes/sig-cli-feature-requests.
If a particular issue has a high impact for you or your business,
make sure this is clear on the bug, and reach out to the sig leads
directly. Consider attending the sig meeting to discuss over video
conference.
## What to do if your PR is stuck
It may happen that your PR seems to be stuck without clear actionable
feedback for a week or longer. If your PR is based off a design proposal,
the chances of the PR getting stuck for a long period of time
are much smaller. However, if it happens do the following:
- If your PR is stuck for a week or more because it has never gotten any
comments, mention @kubernetes/sig-cli-pr-reviews and ask for attention.
If this is not successful in a day or two, escalate to sig leads or
attend the bi-weekly meeting.
- If your PR is stuck for a week or more after it got comments, but
the attention has died down. Mention the reviewer and comment with
"PTAL" (please take another look). If you are still not able to
get any attention after a couple days, escalate to sig leads by
mentioning them.
## What to do if your design docs is stuck
It may happen that your design doc gets stuck without getting merged
or additional feedback. This may happen for a number of reasons. If you believe that your
design is important and has been dropped, or it is not moving forward,
please add it to the sig cli bi-weekly meeting agenda and email
kubernetes-sig-cli@googlegroups.com notifying the community you would
like to discuss it at the next meeting.
Merge state meanings:
- Merged:
- Ready to be implemented.
- Unmerged:
- Experience and design still being worked out.
- Not a high priority issue but may implement in the future: revisit
in 6 months.
- Unintentionally dropped.
- Closed:
- Not something we plan to implement in the proposed manner.
## General escalation instructions if you get stuck
See the [sig-cli community page](https://github.com/kubernetes/community/tree/master/sig-cli) for points of contact and meeting times:
- attend the sig-cli bi-weekly meeting
- message one fo the sig leads [on slack](https://kubernetes.slack.com/messages/sig-cli/)
- send an email to the [kubernetes-sig-cli@googlegroups.com](https://groups.google.com/forum/#!forum/kubernetes-sig-cli)