{"action":"created","comment":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments/42017573","id":42017573,"diff_hunk":"@@ -535,6 +535,69 @@ The API spec changes should be in a commit separate from your other changes.\n \n TODO(smarterclayton): write this.\n \n+## Alpha, Beta, and Stable Versions\n+\n+New feature development proceeds through a series of stages of increasing maturity:\n+\n+- Development level\n+  - Object Versioning: no convention\n+  - Availability: not commited to main kubernetes repo, and thus not available in offical releases\n+  - Audience: other developers closely collaborating on a feature or proof-of-concept\n+  - Upgradeability, Reliability, Completeness, and Support: no requirements or guarantees\n+- Alpha level\n+  - Object Versioning: API version name contains `alpha` (e.g. `v1alpha1`)\n+  - Availability: committed to main kubernetes repo;  appears in an official release; feature is\n+    disabled by default, but may be enabled by flag\n+  - Audience: developers and expert users interested in giving early feedback on features\n+  - Completeness: some API operations, CLI commands, or UI support may not be implemented;  the API\n+    need not have had an *API review* (an intensive and targeted review of the API, on top of a normal\n+    code review)\n+  - Upgradeability: the object schema and semantics may change in a later software release, without\n+    any provision for preserving objects in an existing cluster;\n+    removing the upgradability concern allows developers to make rapid progress; in particular,\n+    API versions can increment faster than the minor release cadence and the developer need not\n+    maintain multiple versions; developers should still increment the API version when object schema\n+    or semantics change in an [incompatible way](#on-compatibility)\n+  - Cluster Reliability: because the feature is relatively new, and may lack complete end-to-end\n+    tests, enabling the feature via a flag might expose bugs with destabilize the cluster (e.g. a\n+    bug in a control loop might rapidly create excessive numbers of object, exhausting API storage).\n+  - Support: there is *no commitment* from the project to complete the feature; the feature may be\n+    dropped entirely in a later software release\n+  - Recommended Use Cases: only in short-lived testing clusters, due to complexity of upgradeability\n+    and lack of long-term support and lack of upgradability.\n+- Beta level:\n+  - Object Versioning: API version name contains `beta` (e.g. `v2beta3`)\n+  - Availability: in official Kubernetes releases, and enabled by default\n+  - Audience: users interested in providing feedback on features\n+  - Completeness: all API operations, CLI commands, and UI support should be implemented; end-to-end\n+    tests complete; the API has had a thorough API review and is thought to be complete, though use\n+    during beta may frequently turn up API issues not thought of during review\n+  - Upgradeability: the object schema and semantics may change in a later software release; when\n+    this happens, an upgrade path will be documentedr; in some cases, objects will be automatically","path":"docs/devel/api_changes.md","position":42,"original_position":42,"commit_id":"ca6c950b897c53f5b5cd4875ce6683f51b781830","original_commit_id":"ca6c950b897c53f5b5cd4875ce6683f51b781830","user":{"login":"lavalamp","id":647318,"avatar_url":"https://avatars.githubusercontent.com/u/647318?v=3","gravatar_id":"","url":"https://api.github.com/users/lavalamp","html_url":"https://github.com/lavalamp","followers_url":"https://api.github.com/users/lavalamp/followers","following_url":"https://api.github.com/users/lavalamp/following{/other_user}","gists_url":"https://api.github.com/users/lavalamp/gists{/gist_id}","starred_url":"https://api.github.com/users/lavalamp/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lavalamp/subscriptions","organizations_url":"https://api.github.com/users/lavalamp/orgs","repos_url":"https://api.github.com/users/lavalamp/repos","events_url":"https://api.github.com/users/lavalamp/events{/privacy}","received_events_url":"https://api.github.com/users/lavalamp/received_events","type":"User","site_admin":false},"body":"s/documentedr/documented/","created_at":"2015-10-14T16:33:06Z","updated_at":"2015-10-14T16:33:06Z","html_url":"https://github.com/kubernetes/kubernetes/pull/15339#discussion_r42017573","pull_request_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339","_links":{"self":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments/42017573"},"html":{"href":"https://github.com/kubernetes/kubernetes/pull/15339#discussion_r42017573"},"pull_request":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339"}}},"pull_request":{"url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339","id":47221314,"html_url":"https://github.com/kubernetes/kubernetes/pull/15339","diff_url":"https://github.com/kubernetes/kubernetes/pull/15339.diff","patch_url":"https://github.com/kubernetes/kubernetes/pull/15339.patch","issue_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339","number":15339,"state":"open","locked":false,"title":"Doc: apigroups, alpha, beta, experimental/v1alpha1","user":{"login":"erictune","id":8105590,"avatar_url":"https://avatars.githubusercontent.com/u/8105590?v=3","gravatar_id":"","url":"https://api.github.com/users/erictune","html_url":"https://github.com/erictune","followers_url":"https://api.github.com/users/erictune/followers","following_url":"https://api.github.com/users/erictune/following{/other_user}","gists_url":"https://api.github.com/users/erictune/gists{/gist_id}","starred_url":"https://api.github.com/users/erictune/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/erictune/subscriptions","organizations_url":"https://api.github.com/users/erictune/orgs","repos_url":"https://api.github.com/users/erictune/repos","events_url":"https://api.github.com/users/erictune/events{/privacy}","received_events_url":"https://api.github.com/users/erictune/received_events","type":"User","site_admin":false},"body":"My attempt to summarize ongoing discussions about versions and stability for a user audience.","created_at":"2015-10-09T00:02:31Z","updated_at":"2015-10-14T16:33:06Z","closed_at":null,"merged_at":null,"merge_commit_sha":"b541037639192dd7c48a6de5a7898b1e86cbfb58","assignee":{"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},"milestone":null,"commits_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/commits","review_comments_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/comments","review_comment_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments{/number}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339/comments","statuses_url":"https://api.github.com/repos/kubernetes/kubernetes/statuses/ca6c950b897c53f5b5cd4875ce6683f51b781830","head":{"label":"erictune:exp-api","ref":"exp-api","sha":"ca6c950b897c53f5b5cd4875ce6683f51b781830","user":{"login":"erictune","id":8105590,"avatar_url":"https://avatars.githubusercontent.com/u/8105590?v=3","gravatar_id":"","url":"https://api.github.com/users/erictune","html_url":"https://github.com/erictune","followers_url":"https://api.github.com/users/erictune/followers","following_url":"https://api.github.com/users/erictune/following{/other_user}","gists_url":"https://api.github.com/users/erictune/gists{/gist_id}","starred_url":"https://api.github.com/users/erictune/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/erictune/subscriptions","organizations_url":"https://api.github.com/users/erictune/orgs","repos_url":"https://api.github.com/users/erictune/repos","events_url":"https://api.github.com/users/erictune/events{/privacy}","received_events_url":"https://api.github.com/users/erictune/received_events","type":"User","site_admin":false},"repo":{"id":21629362,"name":"kubernetes","full_name":"erictune/kubernetes","owner":{"login":"erictune","id":8105590,"avatar_url":"https://avatars.githubusercontent.com/u/8105590?v=3","gravatar_id":"","url":"https://api.github.com/users/erictune","html_url":"https://github.com/erictune","followers_url":"https://api.github.com/users/erictune/followers","following_url":"https://api.github.com/users/erictune/following{/other_user}","gists_url":"https://api.github.com/users/erictune/gists{/gist_id}","starred_url":"https://api.github.com/users/erictune/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/erictune/subscriptions","organizations_url":"https://api.github.com/users/erictune/orgs","repos_url":"https://api.github.com/users/erictune/repos","events_url":"https://api.github.com/users/erictune/events{/privacy}","received_events_url":"https://api.github.com/users/erictune/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/erictune/kubernetes","description":"Container Cluster Manager","fork":true,"url":"https://api.github.com/repos/erictune/kubernetes","forks_url":"https://api.github.com/repos/erictune/kubernetes/forks","keys_url":"https://api.github.com/repos/erictune/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/erictune/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/erictune/kubernetes/teams","hooks_url":"https://api.github.com/repos/erictune/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/erictune/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/erictune/kubernetes/events","assignees_url":"https://api.github.com/repos/erictune/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/erictune/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/erictune/kubernetes/tags","blobs_url":"https://api.github.com/repos/erictune/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/erictune/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/erictune/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/erictune/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/erictune/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/erictune/kubernetes/languages","stargazers_url":"https://api.github.com/repos/erictune/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/erictune/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/erictune/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/erictune/kubernetes/subscription","commits_url":"https://api.github.com/repos/erictune/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/erictune/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/erictune/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/erictune/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/erictune/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/erictune/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/erictune/kubernetes/merges","archive_url":"https://api.github.com/repos/erictune/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/erictune/kubernetes/downloads","issues_url":"https://api.github.com/repos/erictune/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/erictune/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/erictune/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/erictune/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/erictune/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/erictune/kubernetes/releases{/id}","created_at":"2014-07-08T21:00:59Z","updated_at":"2015-05-01T23:13:23Z","pushed_at":"2015-10-14T16:06:11Z","git_url":"git://github.com/erictune/kubernetes.git","ssh_url":"git@github.com:erictune/kubernetes.git","clone_url":"https://github.com/erictune/kubernetes.git","svn_url":"https://github.com/erictune/kubernetes","homepage":null,"size":114629,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"kubernetes:master","ref":"master","sha":"11c735cefa8f6c33f78fb9aa7ff858720ced00ab","user":{"login":"kubernetes","id":13629408,"avatar_url":"https://avatars.githubusercontent.com/u/13629408?v=3","gravatar_id":"","url":"https://api.github.com/users/kubernetes","html_url":"https://github.com/kubernetes","followers_url":"https://api.github.com/users/kubernetes/followers","following_url":"https://api.github.com/users/kubernetes/following{/other_user}","gists_url":"https://api.github.com/users/kubernetes/gists{/gist_id}","starred_url":"https://api.github.com/users/kubernetes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kubernetes/subscriptions","organizations_url":"https://api.github.com/users/kubernetes/orgs","repos_url":"https://api.github.com/users/kubernetes/repos","events_url":"https://api.github.com/users/kubernetes/events{/privacy}","received_events_url":"https://api.github.com/users/kubernetes/received_events","type":"Organization","site_admin":false},"repo":{"id":20580498,"name":"kubernetes","full_name":"kubernetes/kubernetes","owner":{"login":"kubernetes","id":13629408,"avatar_url":"https://avatars.githubusercontent.com/u/13629408?v=3","gravatar_id":"","url":"https://api.github.com/users/kubernetes","html_url":"https://github.com/kubernetes","followers_url":"https://api.github.com/users/kubernetes/followers","following_url":"https://api.github.com/users/kubernetes/following{/other_user}","gists_url":"https://api.github.com/users/kubernetes/gists{/gist_id}","starred_url":"https://api.github.com/users/kubernetes/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kubernetes/subscriptions","organizations_url":"https://api.github.com/users/kubernetes/orgs","repos_url":"https://api.github.com/users/kubernetes/repos","events_url":"https://api.github.com/users/kubernetes/events{/privacy}","received_events_url":"https://api.github.com/users/kubernetes/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/kubernetes/kubernetes","description":"Container Cluster Manager from Google","fork":false,"url":"https://api.github.com/repos/kubernetes/kubernetes","forks_url":"https://api.github.com/repos/kubernetes/kubernetes/forks","keys_url":"https://api.github.com/repos/kubernetes/kubernetes/keys{/key_id}","collaborators_url":"https://api.github.com/repos/kubernetes/kubernetes/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/kubernetes/kubernetes/teams","hooks_url":"https://api.github.com/repos/kubernetes/kubernetes/hooks","issue_events_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/events{/number}","events_url":"https://api.github.com/repos/kubernetes/kubernetes/events","assignees_url":"https://api.github.com/repos/kubernetes/kubernetes/assignees{/user}","branches_url":"https://api.github.com/repos/kubernetes/kubernetes/branches{/branch}","tags_url":"https://api.github.com/repos/kubernetes/kubernetes/tags","blobs_url":"https://api.github.com/repos/kubernetes/kubernetes/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/kubernetes/kubernetes/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/kubernetes/kubernetes/git/refs{/sha}","trees_url":"https://api.github.com/repos/kubernetes/kubernetes/git/trees{/sha}","statuses_url":"https://api.github.com/repos/kubernetes/kubernetes/statuses/{sha}","languages_url":"https://api.github.com/repos/kubernetes/kubernetes/languages","stargazers_url":"https://api.github.com/repos/kubernetes/kubernetes/stargazers","contributors_url":"https://api.github.com/repos/kubernetes/kubernetes/contributors","subscribers_url":"https://api.github.com/repos/kubernetes/kubernetes/subscribers","subscription_url":"https://api.github.com/repos/kubernetes/kubernetes/subscription","commits_url":"https://api.github.com/repos/kubernetes/kubernetes/commits{/sha}","git_commits_url":"https://api.github.com/repos/kubernetes/kubernetes/git/commits{/sha}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/comments{/number}","issue_comment_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/comments{/number}","contents_url":"https://api.github.com/repos/kubernetes/kubernetes/contents/{+path}","compare_url":"https://api.github.com/repos/kubernetes/kubernetes/compare/{base}...{head}","merges_url":"https://api.github.com/repos/kubernetes/kubernetes/merges","archive_url":"https://api.github.com/repos/kubernetes/kubernetes/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/kubernetes/kubernetes/downloads","issues_url":"https://api.github.com/repos/kubernetes/kubernetes/issues{/number}","pulls_url":"https://api.github.com/repos/kubernetes/kubernetes/pulls{/number}","milestones_url":"https://api.github.com/repos/kubernetes/kubernetes/milestones{/number}","notifications_url":"https://api.github.com/repos/kubernetes/kubernetes/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/kubernetes/kubernetes/labels{/name}","releases_url":"https://api.github.com/repos/kubernetes/kubernetes/releases{/id}","created_at":"2014-06-06T22:56:04Z","updated_at":"2015-10-14T16:02:01Z","pushed_at":"2015-10-14T16:06:12Z","git_url":"git://github.com/kubernetes/kubernetes.git","ssh_url":"git@github.com:kubernetes/kubernetes.git","clone_url":"https://github.com/kubernetes/kubernetes.git","svn_url":"https://github.com/kubernetes/kubernetes","homepage":"http://kubernetes.io","size":460696,"stargazers_count":10697,"watchers_count":10697,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":2708,"mirror_url":null,"open_issues_count":2038,"forks":2708,"open_issues":2038,"watchers":10697,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339"},"html":{"href":"https://github.com/kubernetes/kubernetes/pull/15339"},"issue":{"href":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339"},"comments":{"href":"https://api.github.com/repos/kubernetes/kubernetes/issues/15339/comments"},"review_comments":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/comments"},"review_comment":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/kubernetes/kubernetes/pulls/15339/commits"},"statuses":{"href":"https://api.github.com/repos/kubernetes/kubernetes/statuses/ca6c950b897c53f5b5cd4875ce6683f51b781830"}}}}