c19569f03f
Automatic merge from submit-queue Improvements to CLI usability and maintainability Improves `kubectl` from an usability perspective by 1. Fixing how we handle terminal width in help. Some sections like the flags use the entire available width, while others like long descriptions breaks lines but don't follow a well established max width (screenshot below). This PR adds a new responsive writer that will adjust to terminal width and set 80, 100, or 120 columns as the max width, but not more than that given POSIX best practices and recommendations for better readability.  2. Adds our own normalizers for long descriptions and cmd examples which allows us better control about how things like lists, paragraphs, line breaks, etc are printed. Features markdown support. Looks like `templates.LongDesc` and `templates.Examples` instead of `dedent.Dedend`. 3. Allows simple reordering and reuse of help and usage sections. 3. Adds `verify-cli-conventions.sh` which intends to run tests to make sure cmd developers are using what we propose as [kubectl conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/kubectl-conventions.md). Just a couple simple tests for now but the framework is there and it's easy to extend. 4. Update [kubectl conventions](https://github.com/kubernetes/kubernetes/blob/master/docs/devel/kubectl-conventions.md) to use our own normalizers instead of `dedent.Dedent`. **Release note**: <!-- Steps to write your release note: 1. Use the release-note-* labels to set the release note state (if you have access) 2. Enter your extended release note in the below block; leaving it blank means using the PR title as the release note. If no release note is required, just write `NONE`. --> ```release-note Improves how 'kubectl' uses the terminal size when printing help and usage. ``` @kubernetes/kubectl |
||
|---|---|---|
| .. | ||
| developer-guides | ||
| gubernator-images | ||
| local-cluster | ||
| README.md | ||
| adding-an-APIGroup.md | ||
| api-conventions.md | ||
| api_changes.md | ||
| automation.md | ||
| cherry-picks.md | ||
| cli-roadmap.md | ||
| client-libraries.md | ||
| coding-conventions.md | ||
| collab.md | ||
| community-expectations.md | ||
| development.md | ||
| e2e-node-tests.md | ||
| e2e-tests.md | ||
| faster_reviews.md | ||
| flaky-tests.md | ||
| generating-clientset.md | ||
| getting-builds.md | ||
| git_workflow.png | ||
| go-code.md | ||
| godep.md | ||
| gubernator.md | ||
| how-to-doc.md | ||
| instrumentation.md | ||
| issues.md | ||
| kubectl-conventions.md | ||
| kubemark-guide.md | ||
| logging.md | ||
| mesos-style.md | ||
| node-performance-testing.md | ||
| on-call-build-cop.md | ||
| on-call-rotations.md | ||
| on-call-user-support.md | ||
| owners.md | ||
| pr_workflow.dia | ||
| pr_workflow.png | ||
| profiling.md | ||
| pull-requests.md | ||
| running-locally.md | ||
| scheduler.md | ||
| scheduler_algorithm.md | ||
| testing.md | ||
| update-release-docs.md | ||
| updating-docs-for-feature-changes.md | ||
| writing-a-getting-started-guide.md | ||
| writing-good-e2e-tests.md | ||
README.md
PLEASE NOTE: This document applies to the HEAD of the source tree
If you are using a released version of Kubernetes, you should refer to the docs that go with that version.
The latest release of this document can be found [here](http://releases.k8s.io/release-1.4/docs/devel/README.md).Documentation for other releases can be found at releases.k8s.io.
Kubernetes Developer Guide
The developer guide is for anyone wanting to either write code which directly accesses the Kubernetes API, or to contribute directly to the Kubernetes project. It assumes some familiarity with concepts in the User Guide and the Cluster Admin Guide.
The process of developing and contributing code to the Kubernetes project
-
On Collaborative Development (collab.md): Info on pull requests and code reviews.
-
GitHub Issues (issues.md): How incoming issues are reviewed and prioritized.
-
Pull Request Process (pull-requests.md): When and why pull requests are closed.
-
Kubernetes On-Call Rotations (on-call-rotations.md): Descriptions of on-call rotations for build and end-user support.
-
Faster PR reviews (faster_reviews.md): How to get faster PR reviews.
-
Getting Recent Builds (getting-builds.md): How to get recent builds including the latest builds that pass CI.
-
Automated Tools (automation.md): Descriptions of the automation that is running on our github repository.
Setting up your dev environment, coding, and debugging
-
Development Guide (development.md): Setting up your development environment.
-
Hunting flaky tests (flaky-tests.md): We have a goal of 99.9% flake free tests. Here's how to run your tests many times.
-
Logging Conventions (logging.md): Glog levels.
-
Profiling Kubernetes (profiling.md): How to plug in go pprof profiler to Kubernetes.
-
Instrumenting Kubernetes with a new metric (instrumentation.md): How to add a new metrics to the Kubernetes code base.
-
Coding Conventions (coding-conventions.md): Coding style advice for contributors.
-
Document Conventions (how-to-doc.md) Document style advice for contributors.
-
Running a cluster locally (running-locally.md): A fast and lightweight local cluster deployment for development.
Developing against the Kubernetes API
-
The REST API documentation explains the REST API exposed by apiserver.
-
Annotations (docs/user-guide/annotations.md): are for attaching arbitrary non-identifying metadata to objects. Programs that automate Kubernetes objects may use annotations to store small amounts of their state.
-
API Conventions (api-conventions.md): Defining the verbs and resources used in the Kubernetes API.
-
API Client Libraries (client-libraries.md): A list of existing client libraries, both supported and user-contributed.
Writing plugins
-
Authentication Plugins (docs/admin/authentication.md): The current and planned states of authentication tokens.
-
Authorization Plugins (docs/admin/authorization.md): Authorization applies to all HTTP requests on the main apiserver port. This doc explains the available authorization implementations.
-
Admission Control Plugins (admission_control)
Building releases
See the kubernetes/release repository for details on creating releases and related tools and helper scripts.