diff --git a/contributors/design-proposals/sig-cli/template.md b/contributors/design-proposals/sig-cli/template.md new file mode 100644 index 000000000..ccfcbcf34 --- /dev/null +++ b/contributors/design-proposals/sig-cli/template.md @@ -0,0 +1,38 @@ +# + +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> + diff --git a/sig-cli/README.md b/sig-cli/README.md index b43543948..abbce8548 100644 --- a/sig-cli/README.md +++ b/sig-cli/README.md @@ -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 \ No newline at end of file + - 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 | + diff --git a/sig-cli/contributing.md b/sig-cli/contributing.md new file mode 100644 index 000000000..1746ca177 --- /dev/null +++ b/sig-cli/contributing.md @@ -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)