## 1. Project Overview & Quickstart (kubernetes/kubectl) ## File: README.md > ⚠️ **This is an automatically published [staged repository](https://git.k8s.io/kubernetes/staging#external-repository-staging-area) for Kubernetes**. > Pull requests, should be made to the main Kubernetes repository: [https://github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). > This repository is read-only for importing, and not used for direct contributions. > See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details. # Kubectl [](https://travis-ci.org/kubernetes/kubectl) [](https://godoc.org/k8s.io/kubectl) The `k8s.io/kubectl` repo is used to track issues for the kubectl cli distributed with `k8s.io/kubernetes`. It also contains packages intended for use by client programs. E.g. these packages are vendored into `k8s.io/kubernetes` for use in the [kubectl](https://github.com/kubernetes/kubernetes/tree/master/cmd/kubectl) cli client. That client will eventually move here too. ## Contribution Requirements - Full unit-test coverage. - Go tools compliant (`go get`, `go test`, etc.). It needs to be vendorable somewhere else. - No dependence on `k8s.io/kubernetes`. Dependence on other repositories is fine. - Code must be usefully [commented](https://go.dev/doc/effective_go#commentary). Not only for developers on the project, but also for external users of these packages. - When reviewing PRs, you are encouraged to use Golang's [code review comments](https://github.com/golang/go/wiki/CodeReviewComments) page. - Packages in this repository should aspire to implement sensible, small interfaces and import a limited set of dependencies. ## Community, discussion, contribution, and support See [this document](https://github.com/kubernetes/community/tree/master/sig-cli) for how to reach the maintainers of this project. ### Code of conduct Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md). --- ## File: docs/roadmap/template.md Use this template for writing roadmaps for releases # Release 1.X roadmap ## Planned Features ### Feature Y Short description Owners - Link to design proposal - Link to issue ### Feature Z Short description - Link to design proposal - Link to issue ## Planned Technical Debt Cleanup ## Planned Bug Fixes --- ## File: docs/maintainers/issue_backlog.md # SIG CLI Issue Backlog Grooming work for new and existing contributors - Link: https://goo.gl/YEq33R - Author: @pwittrock - Last updated: 10/25/17 ## Background A goal of SIG CLI is to keep the SIG open to contributions from anyone willing to do the work to get involved. While many folks have shown interest in contributing, we have struggled to keep most folks engaged. Kubernetes recently conducted a survey of new contributors, and major themes were that: - Contributors don’t know where to start - There are too many details to learn before contributing - Communication is hard / everyone is too busy to help - Hard to get reviewers on PRs These challenges can be reduced by: - Providing a backlog for contributors to browse and pull work from. - Scoping work that can be done with minimal experience so folks can pick up and work on it. - Marking issues as good first time issues if they can be done by someone with no experience. - Reducing the need for constant communication by having the work be well defined and clearly scoped in the issues themselves. - Ensuring each issue has a stake holder that is committed to seeing that changes are reviewed. [New Contributors Project]: https://github.com/kubernetes/kubectl/projects/3 ## Contribution lifecycle 1. A [good issue](#what-makes-a-good-issue) is created with description and labels. 1. SIG agrees that work for issue will be accepted. 1. Issue moved to the _backlog_ column in the [New Contributors Project]. 1. Contributor assigns issue to self, or asks issue be assigned if they are not a Kubernetes org member. 1. Issue moved to the _assigned_ column in the [New Contributors Project]. 1. Contributor updates issue weekly with status updates, and pushes work to fork - Periodic feedback provided - Discussion between contributor and stakeholder occurs on issue 1. Contributor sends PR for review - Stakeholder ensures the appropriate reviewers exist - Discussion and updates occur on the PR 1. PR accepted and merged ## What makes a good issue? ### Stakeholder and Contributor A stakeholder typically files the issue, wants to see the work done, and will find reviewers for PRs that address the issue. The contributor is the issue assignee - they provide PRs for review to close the issue. The stakeholder may become the contributor. They must find a new stakeholder to review the work and help follow through on issue closure. ### Encapsulated Issues that require modifying large pieces of existing code are typically hard to accept without multiple reviewers, require a high degree of communication and require knowledge of the existing codebase. This makes them bad candidates for contributors looking to get started independently. Issues with good encapsulation have the following properties: - Minimal wiring or changes to existing code - Can disable / enable with a flag - Easy to review the contribution on its own without needing to examine other parts of the system - Low chance of needing to rebase or conflicting with changes made in parallel ### Consensus on work within the SIG Work described in issues in the backlog should be agreed upon by the SIG. PRs sent for review should have the code reviewed, not the _reason_ for doing the PR. SIG CLI needs to come up with low overhead a process for accepting proposed work. 1. Create an issue for the work 2. SIG agrees to accept work for the issue (as described) if it is completed 3. Add issue to the issue backlog ## Types of code contributions ### Code documentation Documenting code is an excellent starter task. It is easier to merge and get consensus on than writing tests or features. It also provides a structured approach to learning about the system and its components. For the packages that need it most, understanding the code base well enough to document it may be an involved task. - Adding doc.go files to packages that are missing them - Updating doc.go files that are empty placeholders - Adding examples of how to use types and functions to packages - Documenting functions with their purpose and usage ### Test coverage Improving test coverage and augmenting e2e tests with integration tests is also a good candidate for 1st and 2nd time contributors. Writing tests for libraries requires understanding how they behave and are meant to be used. Improving code coverage allows the project to move more quickly by reducing regressions issues that the SIG must field, and by providing a safety net for code reviewers ensuring changes don’t break existing functionality. [e2e tests]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-testing/e2e-tests.md - Write unit tests for functionality currently only covered by integration and [e2e tests]. > Integration tests may run processes, such as the apiserver, but do so locally. > E2e tests run a full Kubernetes cluster (remote). - Write integration tests for functionality currently only covered by [e2e tests]. - Improve coverage for edge cases and different inputs to functions. - Improve handling of invalid arguments. - Refactoring existing tests to pull out common code into reusable functions. > _This should be very well scoped as it impacts existing tests and reviewers need to make sure nothing breaks._ ### New libraries Encapsulated libraries (collections of functions devoted to one simple purpose - e.g. date/time utils) are great contributions for experienced contributors - either programming in Go, or with Kubernetes. Because the libraries are encapsulated, it is easier for reviewers to determine the correctness of their interactions with the existing system. If the functionality is new or can be disabled with a flag, the risk of accepting the change is reduced, improving the chance the change will be accepted. ### Modifying existing libraries Tasks to perform non-trivial changes to existing libraries should be reserved only for folks who have made multiple successful contributions of code - either tests or libraries. PRs to modify existing libraries typically have multiple reviewers, and can have subtle side effects that need to be carefully checked for. Improvements in documentation and testing (above) reduces the burden to modify existing code. ## Managing a backlog issue ### Setting Labels For contributors to pick up new tasks independently, the scope and complexity of the task must be well documented on the issue. We use labels to define the most important metadata about the issues in the backlog. #### Size - size/S > 4-10 hours - size/M > 10-20 hours - size/L > 20+ hours #### Type (docs / tests / feature) - type/code-cleanup > Usually some refactoring or small rewrites of code. - type/code-documentation > Write doc.go with package overview and examples or document types and functions. - type/code-feature > Usually a new go package / library for some functionality. Should be encapsulated. - 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. ### Description - Clear description of what the outcome is - Pointers to examples if they exist - Clear stakeholder who will be responsive to the issue and is committed to getting the functionality added ## Assigning an issue once work has started 1. Contributor messages stakeholder on the issue, and maybe on slack 1. Stakeholder moves issue from backlog to assigned 1. Contributor updates issue weekly and publishes work in progress to a fork > The issue should be updated with a link to the fork. 1. Once work is ready for review, contributor files a PR and notifies the stakeholder ## What is expected as part of contributing a library? ### Documentation - doc.go - Comments on all functions and types ### Tests - Unit tests for functions and types - Integration tests with a local control plane (forthcoming) - Maybe e2e tests (only a couple) ### Ownership of addressing issues - Fix bugs discovered in the contribution after it has been accepted --- ## File: docs/maintainers/MAINTAINERS.md # SIG cli maintainers Guide ## Sustaining engineering tasks The following tasks need to be performed consistently as a part of maintaining the health of SIG cli. We will be developing an oncall rotation for working on these tasks, where the oncall is responsible to doing each task daily. ### Issue triage Routinely monitor the newly filed issues and triage them to make sure we identify regressions. [Kubectl repo](https://github.com/kubernetes/kubectl/issues) [Kubernetes repo](https://github.com/kubernetes/kubernetes/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Asig%2Fcli) Look for: - Requests for help - Don't spend a lot of time on these, but answer and close them if it is easy - Regressions and bugs - Find the root cause - Triage the severity - Issues only occurring in old versions but not in new versions are less severe - Simple issues for new contributors - Label these with "for-new-contributors" - Give them a priority - Make sure they are - Small - Well scoped - In areas of code with minimal technical debt - In areas of code with strong ownership already - Feature requests - Do one of - Close them with an explanation along the lines of "Don't have capacity right now, try reopening in 6 months" - Label them with a "priority" ### Test triage Monitor [test grid](https://testgrid.k8s.io/sig-cli-master) and make sure the tests are passing. If any tests are failing, debug them and send a fix. Ask for help if you get stuck. ### PR review Make sure PRs aren't getting stuck without attention. If reviewers routinely don't respond to PRs within a few days, we should take those reviewers out of the list. Look through the PR list with [SIG cli](https://github.com/kubernetes/kubernetes/pulls?utf8=%E2%9C%93&q=is%3Apr%20is%3Aopen%20label%3Asig%2Fcli) ## New contributor assistance - Look through issues labeled "for-new-contributors" that are assigned, and make sure they are active. If they haven't had activity in a couple days, ping the assignee and ask if help is needed. - Identify issues for new contributors to pick up - Figure out a progression for new contributors to become reviewers ## Per-release tasks ### At the start of the dev cycle - Write planned features for each release - Use the [template](../template.md) ### During code-freeze - Daily look at issues labeled with [sig/cli in the milestone](https://github.com/kubernetes/kubernetes/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Asig%2Fcli%20milestone%3Av1.9%20) and make sure they are owned and make progress - **Note:** You will need to update the milestone in the link to the current milestone ## Every 3-6 months tasks ### (3 months) Report about SIG cli at the community meeting TODO: fill this in ### (6 months) Setup a SIG cli face-to-face TODO: fill this in ## 2. Official Technical Reference & Guides (kubernetes/kubernetes.github.io) # The Kubernetes documentation [](https://app.netlify.com/sites/kubernetes-io-main-staging/deploys) [](https://github.com/kubernetes/website/releases/latest) This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad that you want to contribute! - [Contributing to the docs](#contributing-to-the-docs) - [Localization READMEs](#localization-readmes) ## Using this repository You can run the website locally using [Hugo (Extended version)](https://gohugo.io/), or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website. ## Prerequisites To use this repository, you need the following installed locally: - [npm](https://www.npmjs.com/) - [Go](https://go.dev/) - [Hugo (Extended version)](https://gohugo.io/) - A container runtime, like [Docker](https://www.docker.com/). > [!NOTE] Make sure to install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L11) file. Before you start, install the dependencies. Clone the repository and navigate to the directory: ```bash git clone https://github.com/kubernetes/website.git cd website ``` The Kubernetes website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme), which can be installed via npm. You can also download a pre-configured development container image that includes Hugo and Docsy. Additionally, a Git submodule is used for tools that generate the reference documentation. ### Windows ```powershell # fetch submodule dependencies git submodule update --init --recursive --depth 1 ``` ### Linux / other Unix ```bash # fetch submodule dependencies make module-init ``` ## Running the website using a container To build the site in a container, run the following: ```bash # You can set $CONTAINER_ENGINE to the name of any Docker-like container tool # Render the full website make container-serve # Render only a specific language segment (e.g., English) make container-serve segments=en # Render multiple languages (e.g., English and Korean) make container-serve segments=en,ko ``` **💡 Tip:** Using _Hugo segments_ speeds up local preview builds, by rendering only selected language(s). If you see errors, it probably means that the Hugo container did not have enough computing resources available. To solve it, increase the amount of allowed CPU and memory usage for Docker on your machine ([macOS](https://docs.docker.com/desktop/settings/mac/) and [Windows](https://docs.docker.com/desktop/settings/windows/)). Open up your browser to to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh. ## Running the website locally using Hugo To install dependencies, deploy and test the site locally, run: - For macOS and Linux ```bash npm ci # Render the full site (default) make serve # Render only a specific language segment make serve segments=en # Render multiple language segments make serve segments=en,ko ``` **💡 Tip:** Hugo segments are defined in `hugo.toml` and allow faster rendering by limiting the scope to specific language(s). - For Windows (PowerShell) ```powershell npm ci hugo.exe server --config hugo.toml,hugo.server.toml --buildFuture --environment development ``` This will start the local Hugo server on port 1313. Open up your browser to to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh. ## Building the API reference pages The API reference pages located in `content/en/docs/reference/kubernetes-api` are built from the Swagger specification, also known as OpenAPI specification, using . To update the reference pages for a new Kubernetes release follow these steps: 1. Pull in the `api-ref-generator` submodule: ```bash git submodule update --init --recursive --depth 1 ``` 2. Update the Swagger specification: ```bash curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json ``` 3. In `api-ref-assets/config/`, adapt the files `toc.yaml` and `fields.yaml` to reflect the changes of the new release. 4. Next, build the pages: ```bash make api-reference ``` You can test the results locally by building and serving the site from a container: ```bash make container-serve ``` In a web browser, go to to view the API reference. 5. When all changes of the new contract are reflected into the configuration files `toc.yaml` and `fields.yaml`, create a Pull Request with the newly generated API reference pages. ## Troubleshooting If you experience any issues with running website locally, please refer to the [Troubleshooting section](https://kubernetes.io/docs/contribute/new-content/preview-locally/#troubleshooting) of the contributing documentation. ## Get involved with SIG Docs Learn more about SIG Docs Kubernetes community and meetings on the [community page](https://github.com/kubernetes/community/tree/main/sig-docs#meetings). You can also reach the maintainers of this project at: - [Slack](https://kubernetes.slack.com/messages/sig-docs) - [Get an invite for this Slack](https://slack.k8s.io/) - [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) ## Contributing to the docs You can click the **Fork** button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a _fork_. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it. Once your pull request is created, a Kubernetes reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request, **it is your responsibility to modify your pull request to address the feedback that has been provided to you by the Kubernetes reviewer.** Also, note that you may end up having more than one Kubernetes reviewer provide you feedback or you may end up getting feedback from a Kubernetes reviewer that is different than the one initially assigned to provide you feedback. Furthermore, in some cases, one of your reviewers might ask for a technical review from a Kubernetes tech reviewer when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances. For more information about contributing to the Kubernetes documentation, see: - [Contribute to Kubernetes docs](https://kubernetes.io/docs/contribute/) - [Page Content Types](https://kubernetes.io/docs/contribute/style/page-content-types/) - [Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) - [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/) - [Introduction to Kubernetes Docs](https://www.youtube.com/watch?v=pprMgmNzDcw) ### New contributor ambassadors If you need help at any point when contributing, the [New Contributor Ambassadors](https://kubernetes.io/docs/contribute/advanced/#serve-as-a-new-contributor-ambassador) are a good point of contact. These are SIG Docs approvers whose responsibilities include mentoring new contributors and helping them through their first few pull requests. The best place to contact the New Contributors Ambassadors would be on the [Kubernetes Slack](https://slack.k8s.io/). Current New Contributors Ambassadors for SIG Docs: | Name | Slack | GitHub | | -------------------------- | -------------------------- | -------------------------- | | Sreeram Venkitesh | @sreeram.venkitesh | @sreeram-venkitesh | ## Localization READMEs | Language | Language | | -------------------------- | -------------------------- | | [Bengali](./content/bn/README.md) | [Korean](./content/ko/README.md) | | [Chinese](./content/zh-cn/README.md) | [Polish](./content/pl/README.md) | | [French](./content/fr/README.md) | [Portuguese](./content/pt-br/README.md) | | [German](./content/de/README.md) | [Russian](./content/ru/README.md) | | [Hindi](./content/hi/README.md) | [Spanish](./content/es/README.md) | | [Indonesian](./content/id/README.md) | [Ukrainian](./content/uk/README.md) | | [Italian](./content/it/README.md) | [Vietnamese](./content/vi/README.md) | | [Japanese](./content/ja/README.md) | | ## Code of conduct Participation in the Kubernetes community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). ## Thank you Kubernetes thrives on community participation, and we appreciate your contributions to our website and our documentation!