Skip to content

Latest commit

 

History

History
313 lines (235 loc) · 12.1 KB

CONTRIBUTING.md

File metadata and controls

313 lines (235 loc) · 12.1 KB

Contributing

The process for contributing code to Kubernetes via the sig-multicluster community.

TL;DR

Before You Begin

Welcome to the Kubernetes sig-multicluster 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. 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

Understand the big picture

Agree to contribution rules

Follow the CLA signup instructions.

Adopt an issue

New contributors can try the following to work on an existing bug or approved design:

  • In slack (signup here), @mention a lead 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?

  • 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

Filing a bug

  1. An issue is filed that
  • includes steps to reproduce the issue including client / server version,
  • mentions @kubernetes/sig-multicluster-bugs.

Sending a fix

  1. A PR fixing the issue is implemented that
  • includes unit and test-cmd tests,
  • incorporates review feedback,
  • description includes Closes #<Issue Number> or Fixes #<Issue Number>,
  • description or comment @mentions @kubernetes/sig-multicluster-pr-reviews.
  1. Fix appears in the next Kubernetes release!

Feature requests

New contributors: Please start by adopting an existing issue.

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.

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.

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. 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.
  1. Merge the associated KEP PR (if applicable) as provisional after approval and announcement.
  2. A lead 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,
    • docs are completed,
    • feature is designated alpha, beta or GA.
  3. Implement the code per discussion in bug lifecycle.
  4. Update docs.
  5. Wait for your feature to appear in the next Kubernetes or SIG-MC subproject release!

Design Proposals and KEPs

New contributors: Please start by adopting an existing issue.

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.

Once a lead 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.

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.
  • No, this problem should be solved in another way.

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 KEP has been merged.

See the development guide for instructions on setting up the Kubernetes development environment.

Implementation PRs should

  • 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.

Report progress

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:

  1. What's finished?
  2. What's part is being worked on now?
  3. Anything blocking?

Documentation

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.

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

  • 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.
    • Not something we plan to revisit in the next 12 months.

Escalation

If your bug issue is stuck

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.

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 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.

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.

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 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.

General escalation instructions

See the sig-multicluster community page for points of contact and meeting times:

Use of @mentions

  • @{any lead} solicit opinion or advice from leads.
  • @kubernetes/sig-multicluster-bugs sig-multicluster centric bugs.
  • @kubernetes/sig-multicluster-pr-reviews triggers review of code fix PR.
  • @kubernetes/sig-multicluster-feature-requests flags a feature request.
  • @kubernetes/sig-multicluster-proposals flags a design proposal.