diff --git a/sig-multicluster/CONTRIBUTING.md b/sig-multicluster/CONTRIBUTING.md index 93af05549..67a3c855d 100644 --- a/sig-multicluster/CONTRIBUTING.md +++ b/sig-multicluster/CONTRIBUTING.md @@ -1,15 +1,18 @@ # Contributing -The process for contributing code to Kubernetes via the sig-multicluster [community][community page]. +The process for contributing code to Kubernetes via the sig-multicluster +[community][community page]. ## TL;DR -- See [multicluster.sigs.k8s.io/contributing](https://multicluster.sigs.k8s.io/contributing/) -- The sig-multicluster [community page] lists sig-multicluster [leads] - and group [meeting] times. +- See + [multicluster.sigs.k8s.io/contributing](https://multicluster.sigs.k8s.io/contributing/). +- The sig-multicluster [community page] lists sig-multicluster [leads] and group + [meeting] times. - Request a feature by making an [issue] and mentioning `@kubernetes/sig-multicluster-feature-requests`. -- Reach out on Slack in [#sig-multicluster](https://kubernetes.slack.com/messages/sig-multicluster) +- Reach out on Slack in + [#sig-multicluster](https://kubernetes.slack.com/messages/sig-multicluster) - Write a design proposal before starting work on a new feature. - Write [tests]! @@ -18,13 +21,13 @@ The process for contributing code to Kubernetes via the sig-multicluster [commun Welcome to the Kubernetes sig-multicluster contributing guide. We are excited about the prospect of you joining our [community][community page]! -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 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. -If you are interested in contributing to Kubernetes as a whole there is -a top level [contributor's guide][contributors guide] +If you are interested in contributing to Kubernetes as a whole there is a top +level [contributor's guide][contributors guide] ### Understand the big picture @@ -36,23 +39,25 @@ Follow the [CLA signup instructions](../CLA.md). ### Adopt an issue -New contributors can try the following to work on an existing bug or approved design: +New contributors can try the following to work on an existing bug or approved +design: -- In [slack][slack-messages] (signup [here][slack-signup]), - @mention a [lead][leads] and ask if there are any issues you could pick up. - We also maintain a list of [multi cluster issues where help is wanted][multicluster_help_wanted_issues]. - Most of them are not very complex, so that's probably a good starting point. - Leads can recommend issues that have enough priority to receive PR review bandwidth. +- 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. - Send an email to the _kubernetes-sig-multicluster@googlegroups.com_ [group] > Subject: New sig-multicluster 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? + > 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? -- Attend a sig-multicluster [meeting] and introduce yourself as looking to get started. +- Attend a sig-multicluster [meeting] and introduce yourself as looking to get + started. +- Browse through the open issues in the subprojects of SIG-Multicluster, + especially ones with the "help-wanted" tag. ### Bug lifecycle @@ -75,28 +80,32 @@ New contributors can try the following to work on an existing bug or approved de __New contributors:__ Please start by adopting an [existing issue]. -A feature request is an [issue] mentioning `@kubernetes/sig-multicluster-feature-requests`. +A feature request is an [issue] mentioning +`@kubernetes/sig-multicluster-feature-requests`. -To encourage readership, the issue description should _concisely_ (2-4 sentence) describe -the problem that the feature addresses. +To encourage readership, the issue description should _concisely_ (2-4 sentence) +describe the problem that the feature addresses. ### Feature lifecycle -Working on a feature without getting approval for the user experience -and software design often results in wasted time and effort due to -decisions around names and user experience. +Working on a feature without getting approval for the user experience and +software design often results in wasted time and effort due to decisions around +names and user experience. -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. +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 by filing an [issue] (mention `@kubernetes/sig-multicluster-feature-requests`). -2. Submit a [design proposal] and get it approved by a lead. +1. Identify a problem by filing an [issue] (mention + `@kubernetes/sig-multicluster-feature-requests`). +2. Share a design proposal and get community feedback. 3. Announce the proposal as an [agenda] item for the sig-multicluster [meeting]. - Ensures awareness and feedback. - Should be included in meeting notes sent to the sig-multicluster [group]. -4. _Merge_ the proposal PR after approval and announcement. -5. A [lead][leads] adds the associated feature to the [feature repo], ensuring that +4. _Merge_ the associated KEP PR (if applicable) as provisional after approval + and announcement. +5. A [lead][leads] sponsors the review and approval process of the KEP, ensuring + that - release-related decisions are properly made and communicated, - API changes are vetted, - testing is completed, @@ -104,73 +113,64 @@ any PRs are sent for code review. - feature is designated _alpha_, _beta_ or _GA_. 6. Implement the code per discussion in [bug lifecycle][bug]. 7. Update docs. -8. Wait for your feature to appear in the next Kubernetes release! +8. Wait for your feature to appear in the next Kubernetes or SIG-MC subproject + release! -## Design Proposals +## Design Proposals and KEPs __New contributors:__ Please start by adopting an [existing issue]. -A design proposal is a single markdown document in the [design repo] -that follows the [design template]. - -To make one, -- Prepare the markdown document as a PR to that repo. - - Avoid _Work In Progress_ (WIP) PRs (send it only after - you consider it complete). - - For early feedback, use the email discussion [group]. -- Mention `@kubernetes/sig-multicluster-proposals` in the description. -- Mention the related [feature request]. +A design proposal is an informal Google doc or similar shared with members of +the community through the mailing list [group] or at a regular SIG-Multicluster +[meeting] by adding it to the [agenda]. Expect feedback from 2-3 different sig-multicluster community members. -Incorporate feedback and comment [`PTAL`]. +Once a [lead][leads] has agreed that design and code review resources can be +allocated to tackle the proposal, the details of the user experience and design +should be discussed in the community. -Once a [lead][leads] has agreed (via review commentary) that design -and code review resources can be allocated to tackle the proposal, the -details of the user experience and design should be discussed in the -community. - -This step is _important_; it prevents code churn and thrashing around -issues like flag names, command names, etc. +This step is _important_; it prevents code churn and thrashing around issues +like flag names, command names, etc. It is normal for sig-multicluster community members to push back on feature proposals. sig-multicluster development and review resources are extremely constrained. Community members are free to say - No, not this release (or year). -- This is desirable but we need help on these other existing issues before tackling this. +- This is desirable but we need help on these other existing issues before + tackling this. - No, this problem should be solved in another way. -The proposal can be merged into the [design repo] after [lead][leads] -approval and discussion as a meeting [agenda] item. +Usually at this point the design proposal will be reformatted into a KEP and +follow the [KEP process] like other [multicluster KEPs], even if the +implementation is out-of-tree and not tied to a specific Kubernetes release. Then coding can begin. ## Implementation -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 merged_. +Contributors can begin implementing a feature before any of the above steps have +been completed, but _should not send a PR until the [KEP][multicluster KEPs] has +been merged_. -See the [development guide] for instructions on setting up the -Kubernetes development environment. +See the [development guide] for instructions on setting up the Kubernetes +development environment. Implementation PRs should -- mention the issue of the associated design proposal, -- mention `@kubernetes/sig-multicluster-pr-reviews`, +- mention the issue of the associated KEP, - __include tests__. -Small features and flag changes require only unit/integration tests, -while larger changes require both unit/integration tests and e2e tests. +Small features and flag changes require only unit/integration tests, while +larger changes require both unit/integration tests and e2e tests. ### Report progress -_Leads need your help to ensure that progress is made to -get the feature into a [release]._ +_Leads need your help to ensure that progress is made to get the feature into a +[release]._ -While working on the issue, leave a weekly update on the issue -including: +While working on the issue, leave a weekly update on the issue including: 1. What's finished? 2. What's part is being worked on now? @@ -181,18 +181,22 @@ including: _Let users know about cool new features by updating user facing documentation._ -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 -templates. +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 templates. ## Release -Several 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. If -your feature is not fully complete, _including tests_, it will have -to wait until the next release. +Many of the subprojects in SIG-Multicluster are "out-of-tree", meaning they are +not tied to the core Kubernetes release process. For such features, changes can +be merged at any time at the discretion of the code owners. + +For features requiring a change in core Kubernetes, several 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. If your feature is not fully complete, +_including tests_, it will have to wait until the next release. Check the +[kubernetes release calendar] for timelines. ## Merge state meanings @@ -200,8 +204,8 @@ to wait until the next release. - 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. + - 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. @@ -214,50 +218,50 @@ to wait until the next release. If an issue isn't getting any attention and is unresolved, mention `@kubernetes/sig-multicluster-bugs`. -Highlight the severity and urgency of the issue. For severe issues -escalate by contacting sig [leads] and attending the [meeting]. +Highlight the severity and urgency of the issue. For severe issues escalate by +contacting sig [leads] and attending the [meeting]. ### If your feature request issue is stuck If an issue isn't getting any attention and is unresolved, mention `@kubernetes/sig-multicluster-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. +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. ### If your PR is stuck -It may happen that your PR seems to be stuck without clear actionable -feedback for a week or longer. A PR _associated with a bug or design -proposal_ is much less likely to be stuck than a dangling PR. +It may happen that your PR seems to be stuck without clear actionable feedback +for a week or longer. A PR _associated with a bug or design proposal_ is much +less likely to be stuck than a dangling PR. 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-multicluster-pr-reviews` and ask for attention. -- 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`]. + comments, mention `@kubernetes/sig-multicluster-pr-reviews` and ask for + attention. +- 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`]. -If you are still not able to get any attention after a couple days, -escalate to sig [leads] by mentioning them. +If you are still not able to get any attention after a couple days, escalate to +sig [leads] by mentioning them. -### If your design proposal issue is stuck +### If your design proposal is stuck -It may happen that your design doc gets stuck without getting merged -or additional feedback. If you believe that your design is important -and has been dropped, or it is not moving forward, please add it to -the sig multicluster bi-weekly meeting [agenda] and mail the [group] saying -you'd like to discuss it. +It may happen that your design doc gets stuck without getting merged or +additional feedback. If you believe that your design is important and has been +dropped, or it is not moving forward, please add it to the sig multicluster +bi-weekly meeting [agenda] and mail the [group] saying you'd like to discuss it. ### General escalation instructions -See the sig-multicluster [community page] for points of contact and meeting times: +See the sig-multicluster [community page] for points of contact and meeting +times: - attend the sig-multicluster [meeting] -- message one of the sig leads on [slack][slack-messages] (signup [here][slack-signup]) +- message one of the sig leads on [slack][slack-messages] (signup + [here][slack-signup]) - send an email to the _kubernetes-sig-multicluster@googlegroups.com_ [group]. ## Use of [@mentions] @@ -268,17 +272,21 @@ See the sig-multicluster [community page] for points of contact and meeting time - `@kubernetes/sig-multicluster-feature-requests` flags a feature request. - `@kubernetes/sig-multicluster-proposals` flags a design proposal. -[@mentions]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams -[Kubernetes Basics Tutorial]: https://kubernetes.io/docs/tutorials/kubernetes-basics +[@mentions]: + https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams +[Kubernetes Basics Tutorial]: + https://kubernetes.io/docs/tutorials/kubernetes-basics [PR]: https://help.github.com/articles/creating-a-pull-request [`PTAL`]: https://en.wiktionary.org/wiki/PTAL -[agenda]: https://docs.google.com/document/d/18mk62nOXE_MCSSnb4yJD_8UadtzJrYyJxFwbrgabHe8/edit +[multicluster KEPs]: + [https://github.com/kubernetes/enhancements](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster) +[KEP process]: https://github.com/kubernetes/enhancements +[agenda]: + https://docs.google.com/document/d/18mk62nOXE_MCSSnb4yJD_8UadtzJrYyJxFwbrgabHe8/edit [bug]: #bug-lifecycle [community page]: /sig-multicluster [contributors guide]: /contributors/guide [design proposal]: #design-proposals -[design repo]: https://git.k8s.io/design-proposals-archive/multicluster -[design template]: https://git.k8s.io/design-proposals-archive/Design_Proposal_TEMPLATE.md [development guide]: /contributors/devel/development.md [existing issue]: #adopt-an-issue [feature repo]: https://github.com/kubernetes/features @@ -286,13 +294,18 @@ See the sig-multicluster [community page] for points of contact and meeting time [feature]: https://github.com/kubernetes/features [group]: https://groups.google.com/forum/#!forum/kubernetes-sig-multicluster [issue]: https://github.com/kubernetes/kubernetes/issues -[multicluster_help_wanted_issues]: https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3A"help+wanted"+label%3Asig%2Fmulticluster -[kubectl concept docs]: https://git.k8s.io/kubernetes.github.io/docs/concepts/tools/kubectl +[multicluster_help_wanted_issues]: + https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3A"help+wanted"+label%3Asig%2Fmulticluster +[kubectl concept docs]: + https://git.k8s.io/kubernetes.github.io/docs/concepts/tools/kubectl [kubectl docs]: https://kubernetes.io/docs/user-guide/kubectl-overview [kubernetes/cmd/kubectl]: https://git.k8s.io/kubernetes/cmd/kubectl [kubernetes/pkg/kubectl]: https://git.k8s.io/kubernetes/pkg/kubectl +[kubernetes release calendar]: + https://calendar.google.com/calendar/u/0/embed?src=agst.us_b07popf7t4avmt4km7eq5tk5ao@group.calendar.google.com [leads]: /sig-multicluster#leads -[management overview]: https://kubernetes.io/docs/concepts/tools/kubectl/object-management-overview +[management overview]: + https://kubernetes.io/docs/concepts/tools/kubectl/object-management-overview [meeting]: /sig-multicluster#meetings [release]: #release [slack-messages]: https://kubernetes.slack.com/messages/sig-multicluster