1# SIG CLI Issue Backlog
2
3Grooming work for new and existing contributors
4
5- Link: https://goo.gl/YEq33R
6- Author: @pwittrock
7- Last updated: 10/25/17
8
9
10## Background
11
12A goal of SIG CLI is to keep the SIG open to contributions from anyone willing to do the work to get involved.
13While many folks have shown interest in contributing, we have struggled to keep most folks engaged.
14Kubernetes recently conducted a survey of new contributors, and major themes were that:
15
16- Contributors don’t know where to start
17- There are too many details to learn before contributing
18- Communication is hard / everyone is too busy to help
19- Hard to get reviewers on PRs
20
21These challenges can be reduced by:
22
23- Providing a backlog for contributors to browse and pull work from.
24- Scoping work that can be done with minimal experience so folks can pick up and work on it.
25- Marking issues as good first time issues if they can be done by someone with no experience.
26- Reducing the need for constant communication by having the work be well defined and clearly scoped in the issues
27 themselves.
28- Ensuring each issue has a stake holder that is committed to seeing that changes are reviewed.
29
30[New Contributors Project]: https://github.com/kubernetes/kubectl/projects/3
31
32## Contribution lifecycle
33
341. A [good issue](#what-makes-a-good-issue) is created with description and labels.
351. SIG agrees that work for issue will be accepted.
361. Issue moved to the _backlog_ column in the [New Contributors Project].
371. Contributor assigns issue to self, or asks issue be assigned if they are not a Kubernetes org member.
381. Issue moved to the _assigned_ column in the [New Contributors Project].
391. Contributor updates issue weekly with status updates, and pushes work to fork
40 - Periodic feedback provided
41 - Discussion between contributor and stakeholder occurs on issue
421. Contributor sends PR for review
43 - Stakeholder ensures the appropriate reviewers exist
44 - Discussion and updates occur on the PR
451. PR accepted and merged
46
47## What makes a good issue?
48
49### Stakeholder and Contributor
50
51A stakeholder typically files the issue, wants to see the work done, and will
52find reviewers for PRs that address the issue.
53
54The contributor is the issue assignee - they provide PRs for review
55to close the issue.
56
57The stakeholder may become the contributor. They must find a new stakeholder to
58review the work and help follow through on issue closure.
59
60### Encapsulated
61
62Issues that require modifying large pieces of existing code are typically hard
63to accept without multiple reviewers, require a high degree of communication and require knowledge of the
64existing codebase.
65
66This makes them bad candidates for contributors looking to get started independently.
67
68Issues with good encapsulation have the following properties:
69
70- Minimal wiring or changes to existing code
71- Can disable / enable with a flag
72- Easy to review the contribution on its own without needing to examine other parts of the system
73- Low chance of needing to rebase or conflicting with changes made in parallel
74
75### Consensus on work within the SIG
76
77Work described in issues in the backlog should be agreed upon by the SIG. PRs
78sent for review should have the code reviewed, not the _reason_ for doing the
79PR.
80
81SIG CLI needs to come up with low overhead a process for accepting proposed work.
82
831. Create an issue for the work
842. SIG agrees to accept work for the issue (as described) if it is completed
853. Add issue to the issue backlog
86
87## Types of code contributions
88
89### Code documentation
90
91Documenting code is an excellent starter task. It is easier to merge and get consensus on than writing tests or
92features. It also provides a structured approach to learning about the system and its components.
93For the packages that need it most, understanding the code base well enough to document it may be an involved task.
94
95- Adding doc.go files to packages that are missing them
96- Updating doc.go files that are empty placeholders
97- Adding examples of how to use types and functions to packages
98- Documenting functions with their purpose and usage
99
100### Test coverage
101
102Improving test coverage and augmenting e2e tests with integration tests is also a good candidate for 1st and
1032nd time contributors. Writing tests for libraries requires understanding how they behave and are meant to be used.
104Improving code coverage allows the project to move more quickly by reducing regressions issues that the SIG must field,
105and by providing a safety net for code reviewers ensuring changes don’t break existing functionality.
106
107[e2e tests]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/e2e-tests.md
108
109- Write unit tests for functionality currently only covered by integration and [e2e tests].
110 > Integration tests may run processes, such as the apiserver, but do so locally.
111 > E2e tests run a full Kubernetes cluster (remote).
112- Write integration tests for functionality currently only covered by [e2e tests].
113- Improve coverage for edge cases and different inputs to functions.
114- Improve handling of invalid arguments.
115- Refactoring existing tests to pull out common code into reusable functions.
116 > _This should be very well scoped as it impacts existing tests and reviewers need to make sure nothing breaks._
117
118### New libraries
119
120Encapsulated libraries (collections of functions devoted to one simple purpose - e.g. date/time utils)
121are great contributions for experienced contributors - either programming in Go, or
122with Kubernetes.
123
124Because the libraries are encapsulated, it is easier for reviewers to determine the correctness
125of their interactions with the existing system. If the functionality is new or can be disabled with a flag, the
126risk of accepting the change is reduced, improving the chance the change will be accepted.
127
128### Modifying existing libraries
129
130Tasks to perform non-trivial changes to existing libraries should be reserved only for folks who have made
131multiple successful contributions of code - either tests or libraries. PRs to modify existing libraries typically
132have multiple reviewers, and can have subtle side effects that need to be carefully checked for.
133
134Improvements in documentation and testing (above) reduces the burden to modify existing code.
135
136## Managing a backlog issue
137
138### Setting Labels
139
140For contributors to pick up new tasks independently, the scope and complexity of the task must be well documented
141on the issue. We use labels to define the most important metadata about the issues in the backlog.
142
143#### Size
144- size/S
145 > 4-10 hours
146- size/M
147 > 10-20 hours
148- size/L
149 > 20+ hours
150
151#### Type (docs / tests / feature)
152
153- type/code-cleanup
154 > Usually some refactoring or small rewrites of code.
155- type/code-documentation
156 > Write doc.go with package overview and examples or document types and functions.
157- type/code-feature
158 > Usually a new go package / library for some functionality. Should be encapsulated.
159- type/code-test-coverage
160 > Audit tests for a package. Run coverage tools and also manually look at what functions are missing unit or
161 > integration tests. Write tests for these functions.
162
163### Description
164
165- Clear description of what the outcome is
166- Pointers to examples if they exist
167- Clear stakeholder who will be responsive to the issue and is committed to getting the functionality added
168
169## Assigning an issue once work has started
170
1711. Contributor messages stakeholder on the issue, and maybe on slack
1721. Stakeholder moves issue from backlog to assigned
1731. Contributor updates issue weekly and publishes work in progress to a fork
174 > The issue should be updated with a link to the fork.
1751. Once work is ready for review, contributor files a PR and notifies the stakeholder
176
177## What is expected as part of contributing a library?
178
179### Documentation
180
181- doc.go
182- Comments on all functions and types
183
184### Tests
185
186- Unit tests for functions and types
187- Integration tests with a local control plane (forthcoming)
188- Maybe e2e tests (only a couple)
189
190### Ownership of addressing issues
191
192- Fix bugs discovered in the contribution after it has been accepted
View as plain text