diff --git a/sig-cli/CONTRIBUTING.md b/sig-cli/CONTRIBUTING.md index 7c8ec659a..8c87518ee 100644 --- a/sig-cli/CONTRIBUTING.md +++ b/sig-cli/CONTRIBUTING.md @@ -1,118 +1,213 @@ # Contributing -The process for contributing code to Kubernetes via the sig-cli [community][community page]. +The process for contributing code to Kubernetes via SIG-cli [community][community page]. -## TL;DR +**Note**: This page is focused on helping new contributors become active +members of the community through sustained contributions. -- The sig-cli [community page] lists sig-cli [leads], - channels of [communication], and group [meeting] times. -- New contributors: please start by adopting an [existing issue]. -- Request a feature by making an [issue] and mentioning - `@kubernetes/sig-cli-feature-requests`. -- Write a [design proposal] before starting work on a new feature. -- Write [tests]! - -## Before You Begin +## Introduction Welcome to the Kubernetes sig-cli contributing guide. We are excited about the prospect of you joining our [community][community page]! +Mentoring and on-boarding new contributors is critical to the success +of the project. -Please understand that all contributions to Kubernetes require time -and commitment from the project maintainers to review the ux, software -design, and code. Mentoring and on-boarding new contributors is done -in addition to many other responsibilities. +Please be aware that all contributions to Kubernetes require time +and commitment from project maintainers to direct and review work. +This is done in additional to many other maintainer responsibilities, and +direct engagement from maintainers is a finite resource. -### Understand the big picture +## Pick your track -- Complete the [Kubernetes Basics Tutorial]. -- Be familiar with [kubectl user facing documentation ][kubectl docs]. -- Read the concept guides starting with the [management overview]. +Determine in what capacity you are looking to contribute: -### Modify your own `kubectl` fork +### Guided -Make sure you are ready to immediately get started once you have been -assigned a piece of work. Do this right away. +**Who is this for?** -- Setup your [development environment][development guide]. -- Look at code: - - [kubernetes/cmd/kubectl] is the entry point - - [kubernetes/pkg/kubectl] is the implementation - - Look at how some of the other commands are implemented -- Add a new command to do something simple: - - Add `kubectl hello-world`: print "Hello World" - - Add `kubectl hello-kubernetes -f file`: Print "Hello \ \" - - Add `kubectl hello-kubernetes type/name`: Print "Hello \ \ \" +Contributors looking to engage with the SIG cli community for +a sustained period of time and looking to build working relationships +with existing members. Route to becoming a SIG cli member as +a reviewer or approver. + +**How does it work?** + +Work items come from a backlog of groomed items provided by SIG cli community members. +Each items has a stake holder willing to provide limited direction to contributors +working on it. Contributors typically need to put in 10x the time per-issue as the +maintainers providing direction. Contributors are expected to learn and do research +to complete the task independently with only periodic direction (~weekly). + +**What is expected of contributors?** + +Contributors are expected to make progress on items weekly and +provide periodic updates to any issue they are working on. +Contributors are expected exercise ownership of their code by fixing bugs +that are discovered. + +### Self service + +**Who is this for?** + +Contributors that are looking to contribute only 1 or 2 items, or +have a specific issue they would like to like resolve and are willing +to contribute the solution. + +**How does it work?** + +Contributors are free to pick up any work items that they like. Maintainers +will be focused on directing contributors working on Guided items, so contributors +picking up non-Guided items will have almost no direction or support from maintainers. + +**What is expected of contributors?** + +Contributions must be relatively small, simple, well documented and well tested. +Since maintainers will need to own any code for these contributions, these should +be very limited in scope and contain minimal risk +(e.g. simple regression fixes, improved documentation, improved testing). + +## Before You Begin + +**Note**: Complete the following steps before reaching out to cli community members. ### Agree to contribution rules Follow the [CLA signup instructions](../CLA.md). +### Learn a bit about the kubectl cli + +This is important. + +- Learn about using kubectl with Kubernetes in the [Kubernetes Basics Tutorial]. +- Learn about managing configuration in the [kubectl docs]. + +### Modify your own `kubectl` fork + +Make sure you are ready to immediately get started before you claim any piece of +work. + +- Setup your [development environment][development guide]. + - This is hard. Sorry. We want to make this easier. +- Familiarize yourself with the code: + - [kubernetes/cmd/kubectl] is the entry point + - [kubernetes/pkg/kubectl] is the implementation + - Look at how some of the other commands are implemented +- Try adding a new command to do something simple: + - Add `kubectl hello-world`: print "Hello World" + - Add `kubectl hello-kubernetes -f file`: Print "Hello \ \" + - Add `kubectl hello-kubernetes type/name`: Print "Hello \ \ \" + +**Note:** Consider publishing your command to a fork so a maintainer can look at it. + +## Your first contribution + ### Adopt an issue -New contributors can try the following to work on an existing [bug] or [approved design][design repo]: +Pick up an [issue] from the backlog by commenting on the issue that you would like to work on it. +Be sure to mention the author of the issue as well as the SIG cli members `@seans3` and `@mengqiy`. -- In [slack][slack-messages] (signup [here][slack-signup]), - @mention a [lead][leads] and ask if there are any issues you could pick up. - Leads can recommend issues that have enough priority to receive PR review bandwidth. - We also maintain a list of [CLI issues where help is wanted][cli_help_wanted_issues]. - Most of them are not very complex, so that's probably a good starting point. -- Send an email to the _kubernetes-sig-cli@googlegroups.com_ [group] +Using the following comment will make it easier for us to search for issues folks want to have +assigned to them: - > Subject: New sig-cli contributor _${yourName}_ - > - > Body: Hello, my name is _${yourName}_. I would like to get involved in - > contributing to the Kubernetes project. I have read all of the - > user documentation listed on the community contributing page. - > What should I do next to get started? +`cc @seans3 @mengqiy I would like to take this` -- Attend a sig-cli [meeting] and introduce yourself as looking to get started. +**Note:** Don't do this unless you will start work on the issue within a few days of being assigned. -#### What you need to do to get started on a piece of work +**Note:** GitHub only allows issues to be assigned to GitHub accounts that are part +of the organization or listed as outside collaborators. In order to become an outside +collaborator, contributors have to have shown commitment to the issue by performing some +work. Once you have begun, reach out to the issue author and show them your progress +(e.g. in a fork). -Any issue being worked on by new contributors is a large investment for reviewers and maintainers. -Because this is a big investment of a very limited resource, the issues we assign to -new contributors are things we actually want and need. By picking an issue up, there -is an expectation that you will provide periodic updates so the maintainers know it is -being actively developed. If no updates are made for a week or more and the assignee -is unresponsive, we may assign the issue to someone else. +**Picking your first issue** -Pick up an [issue] from the backlog by commenting on it that you would like to work on it. +For your first issue, we recommend picking an issue labeled with "good first issue" from the [issue] backlog. + +**Picking the right size of issue** Be sure to pick up an issue that is appropriate to the time you are able to commit. +We recommend first time contributors start with small or medium issues. -Following are very rough estimates, but are best effort only. They assume you have a development environment -already set up and are able to build + test your code. +Following are very rough estimates, but are best effort only. They assume you have a +development environment already set up and are able to build a kubectl binary and +use it against a cluster. These estimates assume some knowledge of Go. -- size/S - - 4-8 hours -- size/M +- `size/S` + - 4-10 hours +- `size/M` - 10-20 hours -- size/L +- `size/L` - 20+ hours - +- `size/XL` + - 40-80 hours + Meta/Umbrella issues may have multiple components. By signing up for a Meta/Umbrella issue, -you only need to work on the next pieces. +you are only committing to one piece of it. Let the issue author know when you have completed +some piece of it, and if you would like to continue working on it, or have it unassigned. -**Important**: +**Picking the right kind of issue** + +Guided issues have a *type* defining the type of work to be done. Pick up an +issue that fits your experience level and interest. Documentation and +test-coverage issues typically are smaller in scope and easier to complete than +features and cleanup issues. + +- `type/code-cleanup` + - Usually some refactoring or small rewrites of code. +- `type/code-documentation` + - Write `doc.go` with package overview and examples or add code comments to document + existing types and functions. +- `type/code-feature` + - Usually a new go package / library for some functionality that is requested. + Should be encapsulated in its own interfaces with thorough unit tests for the new library. +- `type/code-test-coverage` + - Audit tests for a package. Run coverage tools and also manually look at what functions + are missing unit or integration tests. Write tests for these functions. + +**Provide periodic status updates** + +Once you have requested an issue and it has been accepted, you will be expected +to provide periodic updates to it. Do update the issue with your status at least every +week, and publish your work to a fork so the community can see your progress and +provide early feedback. + +If you find the issue is too challenging, time consuming, or you are no longer able to work on it, +this is perfectly acceptable and please let the issue author know. +If you like, you may pick up a different issue immediately or sometime in the future. + +**Summary**: -- When you pick up an issue, be sure to comment and cc @seans3 and @mengqiy - - To have an issue assigned to you, you must first become an outside collaborator, which - means having made some contribution already. - Don't pick up an issue until you are ready to start working on it -- Update the issue every 2-3 days with your progress so we know it is being worked on. - There is an expectation that continual progress will be made on the issue while it is assigned. +- When you want to pick up an issue, be sure to comment `@seans3` and `@mengqiy`. + Expect a response within 2 days. +- Update the issue every week with your progress so we know it is being actively worked on. +- There is an expectation that some time will be committed to working on the issue each + week until it is completed, or you are blocked on a maintainer. -### Bug lifecycle +### Meet the community -1. An [issue] is filed that - - includes steps to reproduce the issue including client / server version, - - mentions `@kubernetes/sig-cli-bugs`. -2. A [PR] fixing the issue is implemented that - - __includes unit and test-cmd tests__, - - incorporates review feedback, - - description includes `Closes #` or `Fixes #`, - - description or comment @mentions `@kubernetes/sig-cli-pr-reviews`. -3. Fix appears in the next Kubernetes release! +Engage with the SIG cli community! Let us know who you are and how things are going! + +- Fill out the [about me form] so we know a bit about you and can direct your work accordingly. + - **Note:** After filling out the form, reach out via slack or the googlegroup and let us know. + +- Message the [cli mentors] googlegroup and let them know you filled out the form + and are looking to get started. + +- In [slack][slack-messages] (signup [here][slack-signup]), + @mention a [lead][leads] and ask if there are any issues you could pick up, or + let them know what you are working on. + +- Attend a sig-cli [meeting] and introduce yourself and what you are working on. + +- The sig-cli [community page] lists sig-cli [leads], channels of [communication], +and group [meeting] times. + +## Information about how Features are developed + +Once you have made several contributions, you may want to start developing +features that you come up with. This section is about how to propose new +features and get them accepted. ## Feature requests @@ -330,9 +425,7 @@ See the sig-cli [community page] for points of contact and meeting times: [feature]: https://github.com/kubernetes/features [group]: https://groups.google.com/forum/#!forum/kubernetes-sig-cli [issue]: https://github.com/kubernetes/kubectl/projects/3 -[cli_help_wanted_issues]: https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3Asig%2Fcli+label%3Ahelp-wanted -[kubectl concept docs]: https://github.com/kubernetes/kubernetes.github.io/tree/master/docs/concepts/tools/kubectl -[kubectl docs]: https://kubernetes.io/docs/user-guide/kubectl-overview +[kubectl docs]: https://kubernetes.io/docs/tutorials/object-management-kubectl/object-management/ [kubernetes/cmd/kubectl]: https://github.com/kubernetes/kubernetes/tree/master/cmd/kubectl [kubernetes/pkg/kubectl]: https://github.com/kubernetes/kubernetes/tree/master/pkg/kubectl [leads]: https://github.com/kubernetes/community/tree/master/sig-cli#leads @@ -342,3 +435,5 @@ See the sig-cli [community page] for points of contact and meeting times: [slack-messages]: https://kubernetes.slack.com/messages/sig-cli [slack-signup]: http://slack.k8s.io/ [tests]: https://github.com/kubernetes/community/blob/master/contributors/devel/testing.md +[cli mentors]: https://groups.google.com/a/google.com/forum/#!forum/kubernetes-sig-cli-mentors +[about me form]: https://docs.google.com/forms/d/1ID6DX1abiDr9Z9_sXXC0DsMwuyHb_NeFdB3xeRa4Vf0 \ No newline at end of file