{"action":"created","comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments/36794915","id":36794915,"diff_hunk":"@@ -0,0 +1,115 @@\n+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->\n+\n+<!-- BEGIN STRIP_FOR_RELEASE -->\n+\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+<img src=\"http://kubernetes.io/img/warning.png\" alt=\"WARNING\"\n+     width=\"25\" height=\"25\">\n+\n+<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>\n+\n+If you are using a released version of Kubernetes, you should\n+refer to the docs that go with that version.\n+\n+<strong>\n+The latest 1.0.x release of this document can be found\n+[here](http://releases.k8s.io/release-1.0/docs/devel/kubectl-conventions.md).\n+\n+Documentation for other releases can be found at\n+[releases.k8s.io](http://releases.k8s.io).\n+</strong>\n+--\n+\n+<!-- END STRIP_FOR_RELEASE -->\n+\n+<!-- END MUNGE: UNVERSIONED_WARNING -->\n+\n+Kubectl Conventions\n+===================\n+\n+Updated: 8/10/2015\n+\n+**Table of Contents**\n+<!-- BEGIN MUNGE: GENERATED_TOC -->\n+\n+  - [Principles](#principles)\n+  - [Command conventions](#command-conventions)\n+  - [Flag conventions](#flag-conventions)\n+  - [Output conventions](#output-conventions)\n+  - [Documentation conventions](#documentation-conventions)\n+\n+<!-- END MUNGE: GENERATED_TOC -->\n+\n+## Principles\n+\n+* Strive for consistency across commands\n+* Explicit should always override implicit\n+  * Environment variables should override default values\n+  * Command-line flags should override default values and environment variables\n+    * --namespace should also override the value specified in a specified resource\n+\n+## Command conventions\n+\n+* Command names are all lowercase, and hyphenated if multiple words.\n+* kubectl VERB NOUNs for commands that apply to multiple resource types\n+* NOUNs may be specified as TYPE name1 name2 ... or TYPE/name1 TYPE/name2; TYPE is omitted when only a single type is expected\n+* Resource types are all lowercase, with no hyphens; both singular and plural forms are accepted\n+* NOUNs may also be specified by one or more file arguments: -f file1 -f file2 ...\n+* Resource types may have 2- or 3-letter aliases.\n+* Business logic should be decoupled from the command framework, so that it can be reused independently of kubectl, cobra, etc.\n+  * Ideally, commonly needed functionality would be implemented server-side in order to avoid problems typical of \"fat\" clients and to make it readily available to non-Go clients\n+* Commands that generate resources, such as `run` or `expose`, should obey the following conventions:\n+  * Flags should be converted to a parameter Go map or json map prior to invoking the generator\n+  * The generator must be versioned so that users depending on a specific behavior may pin to that version, via `--generator=`\n+  * Generation should be decoupled from creation\n+  * `--dry-run` should output the resource that would be created, without creating it\n+* A command group (e.g., `kubectl config`) may be used to group related non-standard commands, such as custom generators, mutations, and computations\n+\n+## Flag conventions\n+\n+* Flags are all lowercase, with words separated by hyphens\n+* Flag names and single-character aliases should have the same meaning across all commands\n+* Command-line flags corresponding to API fields should accept API enums exactly (e.g., --restart=Always)\n+\n+## Output conventions\n+\n+* By default, output is intended for humans rather than programs\n+  * However, affordances are made for simple parsing of `get` output\n+* Only errors should be directed to stderr\n+* `get` commands should output one row per resource, and one resource per row\n+  * Column titles and values should not contain spaces in order to facilitate commands that break lines into fields: cut, awk, etc.\n+  * By default, `get` output should fit within about 80 columns\n+    * Eventually we could perhaps auto-detect width\n+    * `-o wide` may be used to display additional columns\n+  * The first column should be the resource name, titled `NAME` (may change this to an abbreviation of resource type)\n+  * NAMESPACE should be displayed as the first column when --all-namespaces is specified\n+  * The last default column should be time since creation, titled `AGE`\n+  * `-Lkey` should append a column containing the value of label with key `key`, with `<none>` if not present\n+  * json, yaml, Go template, and jsonpath template formats should be supported and encouraged for subsequent processing\n+    * Users should use --api-version or --output-version to ensure the output uses the version they expect\n+* `describe` commands may output on multiple lines and may include information from related resources, such as events","path":"docs/devel/kubectl-conventions.md","position":97,"original_position":97,"commit_id":"aeb577eea3bc45b427e8bc56244712f3516f9fb3","original_commit_id":"aeb577eea3bc45b427e8bc56244712f3516f9fb3","user":{"login":"smarterclayton","id":1163175,"avatar_url":"https://avatars.githubusercontent.com/u/1163175?v=3","gravatar_id":"","url":"https://api.github.com/users/smarterclayton","html_url":"https://github.com/smarterclayton","followers_url":"https://api.github.com/users/smarterclayton/followers","following_url":"https://api.github.com/users/smarterclayton/following{/other_user}","gists_url":"https://api.github.com/users/smarterclayton/gists{/gist_id}","starred_url":"https://api.github.com/users/smarterclayton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smarterclayton/subscriptions","organizations_url":"https://api.github.com/users/smarterclayton/orgs","repos_url":"https://api.github.com/users/smarterclayton/repos","events_url":"https://api.github.com/users/smarterclayton/events{/privacy}","received_events_url":"https://api.github.com/users/smarterclayton/received_events","type":"User","site_admin":false},"body":"Add: Describe should add additional information from related resources that a normal user may need to know - if a user would always run \"describe resource1\" and the immediately want to run a \"get type2\" or \"describe resource2\", consider including that info.  Examples, persistent volume claims for pods that reference claims, events for most resources, nodes and the pods scheduled on them.","created_at":"2015-08-11T20:32:33Z","updated_at":"2015-08-11T20:32:33Z","html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/12515#discussion_r36794915","pull_request_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515","_links":{"self":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments/36794915"},"html":{"href":"https://github.com/GoogleCloudPlatform/kubernetes/pull/12515#discussion_r36794915"},"pull_request":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515"}}},"pull_request":{"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515","id":42096775,"html_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/12515","diff_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/12515.diff","patch_url":"https://github.com/GoogleCloudPlatform/kubernetes/pull/12515.patch","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/12515","number":12515,"state":"open","locked":false,"title":"Update API conventions. Add kubectl conventions.","user":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"body":"Ref #12322. Fixes #6797.\r\n\r\ncc @smarterclayton @erictune @thockin ","created_at":"2015-08-11T06:33:13Z","updated_at":"2015-08-11T20:32:33Z","closed_at":null,"merged_at":null,"merge_commit_sha":"bdb986436ceaeea7a87f5bf8605aec34004047f3","assignee":{"login":"smarterclayton","id":1163175,"avatar_url":"https://avatars.githubusercontent.com/u/1163175?v=3","gravatar_id":"","url":"https://api.github.com/users/smarterclayton","html_url":"https://github.com/smarterclayton","followers_url":"https://api.github.com/users/smarterclayton/followers","following_url":"https://api.github.com/users/smarterclayton/following{/other_user}","gists_url":"https://api.github.com/users/smarterclayton/gists{/gist_id}","starred_url":"https://api.github.com/users/smarterclayton/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/smarterclayton/subscriptions","organizations_url":"https://api.github.com/users/smarterclayton/orgs","repos_url":"https://api.github.com/users/smarterclayton/repos","events_url":"https://api.github.com/users/smarterclayton/events{/privacy}","received_events_url":"https://api.github.com/users/smarterclayton/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515/commits","review_comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515/comments","review_comment_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments{/number}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/12515/comments","statuses_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/statuses/aeb577eea3bc45b427e8bc56244712f3516f9fb3","head":{"label":"bgrant0607:docfix","ref":"docfix","sha":"aeb577eea3bc45b427e8bc56244712f3516f9fb3","user":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"repo":{"id":23933470,"name":"kubernetes","full_name":"bgrant0607/kubernetes","owner":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/bgrant0607/kubernetes","description":"Container Cluster Manager","fork":true,"url":"https://api.github.com/repos/bgrant0607/kubernetes","forks_url":"https://api.github.com/repos/bgrant0607/kubernetes/forks","keys_url":"https://api.github.com/repos/bgrant0607/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/bgrant0607/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/bgrant0607/kubernetes/teams","hooks_url":"https://api.github.com/repos/bgrant0607/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/bgrant0607/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/bgrant0607/kubernetes/events","assignees_url":"https://api.github.com/repos/bgrant0607/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/bgrant0607/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/bgrant0607/kubernetes/tags","blobs_url":"https://api.github.com/repos/bgrant0607/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/bgrant0607/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/bgrant0607/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/bgrant0607/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/bgrant0607/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/bgrant0607/kubernetes/languages","stargazers_url":"https://api.github.com/repos/bgrant0607/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/bgrant0607/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/bgrant0607/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/bgrant0607/kubernetes/subscription","commits_url":"https://api.github.com/repos/bgrant0607/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/bgrant0607/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/bgrant0607/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/bgrant0607/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/bgrant0607/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/bgrant0607/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/bgrant0607/kubernetes/merges","archive_url":"https://api.github.com/repos/bgrant0607/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/bgrant0607/kubernetes/downloads","issues_url":"https://api.github.com/repos/bgrant0607/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/bgrant0607/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/bgrant0607/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/bgrant0607/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/bgrant0607/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/bgrant0607/kubernetes/releases{/id}","created_at":"2014-09-11T19:55:59Z","updated_at":"2015-01-20T22:09:04Z","pushed_at":"2015-08-11T06:32:16Z","git_url":"git://github.com/bgrant0607/kubernetes.git","ssh_url":"git@github.com:bgrant0607/kubernetes.git","clone_url":"https://github.com/bgrant0607/kubernetes.git","svn_url":"https://github.com/bgrant0607/kubernetes","homepage":null,"size":99222,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"GoogleCloudPlatform:master","ref":"master","sha":"3f1864185756dad1622c26cbd3d1fbd56b3eb5ba","user":{"login":"GoogleCloudPlatform","id":2810941,"avatar_url":"https://avatars.githubusercontent.com/u/2810941?v=3","gravatar_id":"","url":"https://api.github.com/users/GoogleCloudPlatform","html_url":"https://github.com/GoogleCloudPlatform","followers_url":"https://api.github.com/users/GoogleCloudPlatform/followers","following_url":"https://api.github.com/users/GoogleCloudPlatform/following{/other_user}","gists_url":"https://api.github.com/users/GoogleCloudPlatform/gists{/gist_id}","starred_url":"https://api.github.com/users/GoogleCloudPlatform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GoogleCloudPlatform/subscriptions","organizations_url":"https://api.github.com/users/GoogleCloudPlatform/orgs","repos_url":"https://api.github.com/users/GoogleCloudPlatform/repos","events_url":"https://api.github.com/users/GoogleCloudPlatform/events{/privacy}","received_events_url":"https://api.github.com/users/GoogleCloudPlatform/received_events","type":"Organization","site_admin":false},"repo":{"id":20580498,"name":"kubernetes","full_name":"GoogleCloudPlatform/kubernetes","owner":{"login":"GoogleCloudPlatform","id":2810941,"avatar_url":"https://avatars.githubusercontent.com/u/2810941?v=3","gravatar_id":"","url":"https://api.github.com/users/GoogleCloudPlatform","html_url":"https://github.com/GoogleCloudPlatform","followers_url":"https://api.github.com/users/GoogleCloudPlatform/followers","following_url":"https://api.github.com/users/GoogleCloudPlatform/following{/other_user}","gists_url":"https://api.github.com/users/GoogleCloudPlatform/gists{/gist_id}","starred_url":"https://api.github.com/users/GoogleCloudPlatform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GoogleCloudPlatform/subscriptions","organizations_url":"https://api.github.com/users/GoogleCloudPlatform/orgs","repos_url":"https://api.github.com/users/GoogleCloudPlatform/repos","events_url":"https://api.github.com/users/GoogleCloudPlatform/events{/privacy}","received_events_url":"https://api.github.com/users/GoogleCloudPlatform/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/GoogleCloudPlatform/kubernetes","description":"Container Cluster Manager from Google","fork":false,"url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes","forks_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/forks","keys_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/teams","hooks_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/events","assignees_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/tags","blobs_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/languages","stargazers_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/subscription","commits_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/merges","archive_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/downloads","issues_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/releases{/id}","created_at":"2014-06-06T22:56:04Z","updated_at":"2015-08-11T20:29:46Z","pushed_at":"2015-08-11T20:30:22Z","git_url":"git://github.com/GoogleCloudPlatform/kubernetes.git","ssh_url":"git@github.com:GoogleCloudPlatform/kubernetes.git","clone_url":"https://github.com/GoogleCloudPlatform/kubernetes.git","svn_url":"https://github.com/GoogleCloudPlatform/kubernetes","homepage":"http://kubernetes.io","size":342424,"stargazers_count":9634,"watchers_count":9634,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":2304,"mirror_url":null,"open_issues_count":1734,"forks":2304,"open_issues":1734,"watchers":9634,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515"},"html":{"href":"https://github.com/GoogleCloudPlatform/kubernetes/pull/12515"},"issue":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/12515"},"comments":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/issues/12515/comments"},"review_comments":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515/comments"},"review_comment":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/pulls/12515/commits"},"statuses":{"href":"https://api.github.com/repos/GoogleCloudPlatform/kubernetes/statuses/aeb577eea3bc45b427e8bc56244712f3516f9fb3"}}}}