{"action":"created","comment":{"url":"https://api.github.com/repos/google/go-cloud/pulls/comments/238474168","pull_request_review_id":181024922,"id":238474168,"node_id":"MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDIzODQ3NDE2OA==","diff_hunk":"@@ -107,6 +107,36 @@ symbols stable over time.\n The exception to this rule is if the name is not unique across providers. The\n canonical example is `gcpkms` and `awskms`.\n \n+## Option Structs in APIs\n+\n+All public constructors should take an `Options` struct, even if it is currently\n+empty, to ensure that we can add arguments to the APIs in the future without\n+breaking backward compatibility.\n+\n+-   This includes driver constructors (e.g., `gcsblob.OpenBucket`) as well as\n+    API functions (e.g., `blob.NewReader`). When in doubt, if you think it's\n+    possible that we'll add arguments, add `Options`.\n+-   Name the `Options` struct appropriately. `Options` is usually fine for\n+    provider constructors since the package generally only exposes a\n+    constructor. Inside a driver interface or in a concrete type like `blob`,\n+    use more descriptive names like `ReaderOptions` or `WriterOptions`.\n+-   When similar `Options` are part of a driver interface and also part of the\n+    concrete type (e.g., `blob.WriterOptions`), duplicate the struct instead of\n+    aliasing or embedding it, and copy the struct fields explicitly where\n+    needed. This allows the godoc for each type to be tailored to the\n+    appropriate audience (concrete type: users, driver interface: provider\n+    implementors), and also allows the structs to diverge over time if\n+    appropriate.\n+-   Arguments that are optional, including ones for which a default value is\n+    common, should generally go into the `Options` struct. Avoid adding\n+    `Options` fields for which the default value doesn't make sense.\n+-   Regarding empty `Options` structs: we considered only adding them the first","path":"internal/docs/design.md","position":36,"original_position":36,"commit_id":"449a128e1fbab36836b42120f2ac3c9480aa184b","original_commit_id":"449a128e1fbab36836b42120f2ac3c9480aa184b","user":{"login":"ijt","id":15530,"node_id":"MDQ6VXNlcjE1NTMw","avatar_url":"https://avatars0.githubusercontent.com/u/15530?v=4","gravatar_id":"","url":"https://api.github.com/users/ijt","html_url":"https://github.com/ijt","followers_url":"https://api.github.com/users/ijt/followers","following_url":"https://api.github.com/users/ijt/following{/other_user}","gists_url":"https://api.github.com/users/ijt/gists{/gist_id}","starred_url":"https://api.github.com/users/ijt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ijt/subscriptions","organizations_url":"https://api.github.com/users/ijt/orgs","repos_url":"https://api.github.com/users/ijt/repos","events_url":"https://api.github.com/users/ijt/events{/privacy}","received_events_url":"https://api.github.com/users/ijt/received_events","type":"User","site_admin":false},"body":"we considered only adding them the first -> we considered only adding them _when_ the first","created_at":"2018-12-03T23:08:21Z","updated_at":"2018-12-03T23:09:46Z","html_url":"https://github.com/google/go-cloud/pull/876#discussion_r238474168","pull_request_url":"https://api.github.com/repos/google/go-cloud/pulls/876","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/google/go-cloud/pulls/comments/238474168"},"html":{"href":"https://github.com/google/go-cloud/pull/876#discussion_r238474168"},"pull_request":{"href":"https://api.github.com/repos/google/go-cloud/pulls/876"}}},"pull_request":{"url":"https://api.github.com/repos/google/go-cloud/pulls/876","id":235605572,"node_id":"MDExOlB1bGxSZXF1ZXN0MjM1NjA1NTcy","html_url":"https://github.com/google/go-cloud/pull/876","diff_url":"https://github.com/google/go-cloud/pull/876.diff","patch_url":"https://github.com/google/go-cloud/pull/876.patch","issue_url":"https://api.github.com/repos/google/go-cloud/issues/876","number":876,"state":"open","locked":false,"title":"docs: document design decisions regarding Options structs in APIs","user":{"login":"vangent","id":22553934,"node_id":"MDQ6VXNlcjIyNTUzOTM0","avatar_url":"https://avatars3.githubusercontent.com/u/22553934?v=4","gravatar_id":"","url":"https://api.github.com/users/vangent","html_url":"https://github.com/vangent","followers_url":"https://api.github.com/users/vangent/followers","following_url":"https://api.github.com/users/vangent/following{/other_user}","gists_url":"https://api.github.com/users/vangent/gists{/gist_id}","starred_url":"https://api.github.com/users/vangent/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vangent/subscriptions","organizations_url":"https://api.github.com/users/vangent/orgs","repos_url":"https://api.github.com/users/vangent/repos","events_url":"https://api.github.com/users/vangent/events{/privacy}","received_events_url":"https://api.github.com/users/vangent/received_events","type":"User","site_admin":false},"body":"","created_at":"2018-12-03T21:54:11Z","updated_at":"2018-12-03T23:09:46Z","closed_at":null,"merged_at":null,"merge_commit_sha":"fdd901daf32d9db9a81170ed6829667ff5316771","assignee":{"login":"zombiezen","id":181535,"node_id":"MDQ6VXNlcjE4MTUzNQ==","avatar_url":"https://avatars2.githubusercontent.com/u/181535?v=4","gravatar_id":"","url":"https://api.github.com/users/zombiezen","html_url":"https://github.com/zombiezen","followers_url":"https://api.github.com/users/zombiezen/followers","following_url":"https://api.github.com/users/zombiezen/following{/other_user}","gists_url":"https://api.github.com/users/zombiezen/gists{/gist_id}","starred_url":"https://api.github.com/users/zombiezen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zombiezen/subscriptions","organizations_url":"https://api.github.com/users/zombiezen/orgs","repos_url":"https://api.github.com/users/zombiezen/repos","events_url":"https://api.github.com/users/zombiezen/events{/privacy}","received_events_url":"https://api.github.com/users/zombiezen/received_events","type":"User","site_admin":false},"assignees":[{"login":"zombiezen","id":181535,"node_id":"MDQ6VXNlcjE4MTUzNQ==","avatar_url":"https://avatars2.githubusercontent.com/u/181535?v=4","gravatar_id":"","url":"https://api.github.com/users/zombiezen","html_url":"https://github.com/zombiezen","followers_url":"https://api.github.com/users/zombiezen/followers","following_url":"https://api.github.com/users/zombiezen/following{/other_user}","gists_url":"https://api.github.com/users/zombiezen/gists{/gist_id}","starred_url":"https://api.github.com/users/zombiezen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/zombiezen/subscriptions","organizations_url":"https://api.github.com/users/zombiezen/orgs","repos_url":"https://api.github.com/users/zombiezen/repos","events_url":"https://api.github.com/users/zombiezen/events{/privacy}","received_events_url":"https://api.github.com/users/zombiezen/received_events","type":"User","site_admin":false}],"requested_reviewers":[{"login":"clausti","id":4240737,"node_id":"MDQ6VXNlcjQyNDA3Mzc=","avatar_url":"https://avatars0.githubusercontent.com/u/4240737?v=4","gravatar_id":"","url":"https://api.github.com/users/clausti","html_url":"https://github.com/clausti","followers_url":"https://api.github.com/users/clausti/followers","following_url":"https://api.github.com/users/clausti/following{/other_user}","gists_url":"https://api.github.com/users/clausti/gists{/gist_id}","starred_url":"https://api.github.com/users/clausti/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/clausti/subscriptions","organizations_url":"https://api.github.com/users/clausti/orgs","repos_url":"https://api.github.com/users/clausti/repos","events_url":"https://api.github.com/users/clausti/events{/privacy}","received_events_url":"https://api.github.com/users/clausti/received_events","type":"User","site_admin":false},{"login":"shantuo","id":8689543,"node_id":"MDQ6VXNlcjg2ODk1NDM=","avatar_url":"https://avatars3.githubusercontent.com/u/8689543?v=4","gravatar_id":"","url":"https://api.github.com/users/shantuo","html_url":"https://github.com/shantuo","followers_url":"https://api.github.com/users/shantuo/followers","following_url":"https://api.github.com/users/shantuo/following{/other_user}","gists_url":"https://api.github.com/users/shantuo/gists{/gist_id}","starred_url":"https://api.github.com/users/shantuo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/shantuo/subscriptions","organizations_url":"https://api.github.com/users/shantuo/orgs","repos_url":"https://api.github.com/users/shantuo/repos","events_url":"https://api.github.com/users/shantuo/events{/privacy}","received_events_url":"https://api.github.com/users/shantuo/received_events","type":"User","site_admin":false},{"login":"jba","id":18483045,"node_id":"MDQ6VXNlcjE4NDgzMDQ1","avatar_url":"https://avatars1.githubusercontent.com/u/18483045?v=4","gravatar_id":"","url":"https://api.github.com/users/jba","html_url":"https://github.com/jba","followers_url":"https://api.github.com/users/jba/followers","following_url":"https://api.github.com/users/jba/following{/other_user}","gists_url":"https://api.github.com/users/jba/gists{/gist_id}","starred_url":"https://api.github.com/users/jba/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jba/subscriptions","organizations_url":"https://api.github.com/users/jba/orgs","repos_url":"https://api.github.com/users/jba/repos","events_url":"https://api.github.com/users/jba/events{/privacy}","received_events_url":"https://api.github.com/users/jba/received_events","type":"User","site_admin":false}],"requested_teams":[],"labels":[{"id":1016532751,"node_id":"MDU6TGFiZWwxMDE2NTMyNzUx","url":"https://api.github.com/repos/google/go-cloud/labels/cla:%20yes","name":"cla: yes","color":"0e8a16","default":false}],"milestone":null,"commits_url":"https://api.github.com/repos/google/go-cloud/pulls/876/commits","review_comments_url":"https://api.github.com/repos/google/go-cloud/pulls/876/comments","review_comment_url":"https://api.github.com/repos/google/go-cloud/pulls/comments{/number}","comments_url":"https://api.github.com/repos/google/go-cloud/issues/876/comments","statuses_url":"https://api.github.com/repos/google/go-cloud/statuses/449a128e1fbab36836b42120f2ac3c9480aa184b","head":{"label":"vangent:document-options","ref":"document-options","sha":"449a128e1fbab36836b42120f2ac3c9480aa184b","user":{"login":"vangent","id":22553934,"node_id":"MDQ6VXNlcjIyNTUzOTM0","avatar_url":"https://avatars3.githubusercontent.com/u/22553934?v=4","gravatar_id":"","url":"https://api.github.com/users/vangent","html_url":"https://github.com/vangent","followers_url":"https://api.github.com/users/vangent/followers","following_url":"https://api.github.com/users/vangent/following{/other_user}","gists_url":"https://api.github.com/users/vangent/gists{/gist_id}","starred_url":"https://api.github.com/users/vangent/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vangent/subscriptions","organizations_url":"https://api.github.com/users/vangent/orgs","repos_url":"https://api.github.com/users/vangent/repos","events_url":"https://api.github.com/users/vangent/events{/privacy}","received_events_url":"https://api.github.com/users/vangent/received_events","type":"User","site_admin":false},"repo":{"id":143323945,"node_id":"MDEwOlJlcG9zaXRvcnkxNDMzMjM5NDU=","name":"go-cloud","full_name":"vangent/go-cloud","private":false,"owner":{"login":"vangent","id":22553934,"node_id":"MDQ6VXNlcjIyNTUzOTM0","avatar_url":"https://avatars3.githubusercontent.com/u/22553934?v=4","gravatar_id":"","url":"https://api.github.com/users/vangent","html_url":"https://github.com/vangent","followers_url":"https://api.github.com/users/vangent/followers","following_url":"https://api.github.com/users/vangent/following{/other_user}","gists_url":"https://api.github.com/users/vangent/gists{/gist_id}","starred_url":"https://api.github.com/users/vangent/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vangent/subscriptions","organizations_url":"https://api.github.com/users/vangent/orgs","repos_url":"https://api.github.com/users/vangent/repos","events_url":"https://api.github.com/users/vangent/events{/privacy}","received_events_url":"https://api.github.com/users/vangent/received_events","type":"User","site_admin":false},"html_url":"https://github.com/vangent/go-cloud","description":"A library and tools for open cloud development in Go.","fork":true,"url":"https://api.github.com/repos/vangent/go-cloud","forks_url":"https://api.github.com/repos/vangent/go-cloud/forks","keys_url":"https://api.github.com/repos/vangent/go-cloud/keys{/key_id}","collaborators_url":"https://api.github.com/repos/vangent/go-cloud/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/vangent/go-cloud/teams","hooks_url":"https://api.github.com/repos/vangent/go-cloud/hooks","issue_events_url":"https://api.github.com/repos/vangent/go-cloud/issues/events{/number}","events_url":"https://api.github.com/repos/vangent/go-cloud/events","assignees_url":"https://api.github.com/repos/vangent/go-cloud/assignees{/user}","branches_url":"https://api.github.com/repos/vangent/go-cloud/branches{/branch}","tags_url":"https://api.github.com/repos/vangent/go-cloud/tags","blobs_url":"https://api.github.com/repos/vangent/go-cloud/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/vangent/go-cloud/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/vangent/go-cloud/git/refs{/sha}","trees_url":"https://api.github.com/repos/vangent/go-cloud/git/trees{/sha}","statuses_url":"https://api.github.com/repos/vangent/go-cloud/statuses/{sha}","languages_url":"https://api.github.com/repos/vangent/go-cloud/languages","stargazers_url":"https://api.github.com/repos/vangent/go-cloud/stargazers","contributors_url":"https://api.github.com/repos/vangent/go-cloud/contributors","subscribers_url":"https://api.github.com/repos/vangent/go-cloud/subscribers","subscription_url":"https://api.github.com/repos/vangent/go-cloud/subscription","commits_url":"https://api.github.com/repos/vangent/go-cloud/commits{/sha}","git_commits_url":"https://api.github.com/repos/vangent/go-cloud/git/commits{/sha}","comments_url":"https://api.github.com/repos/vangent/go-cloud/comments{/number}","issue_comment_url":"https://api.github.com/repos/vangent/go-cloud/issues/comments{/number}","contents_url":"https://api.github.com/repos/vangent/go-cloud/contents/{+path}","compare_url":"https://api.github.com/repos/vangent/go-cloud/compare/{base}...{head}","merges_url":"https://api.github.com/repos/vangent/go-cloud/merges","archive_url":"https://api.github.com/repos/vangent/go-cloud/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/vangent/go-cloud/downloads","issues_url":"https://api.github.com/repos/vangent/go-cloud/issues{/number}","pulls_url":"https://api.github.com/repos/vangent/go-cloud/pulls{/number}","milestones_url":"https://api.github.com/repos/vangent/go-cloud/milestones{/number}","notifications_url":"https://api.github.com/repos/vangent/go-cloud/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/vangent/go-cloud/labels{/name}","releases_url":"https://api.github.com/repos/vangent/go-cloud/releases{/id}","deployments_url":"https://api.github.com/repos/vangent/go-cloud/deployments","created_at":"2018-08-02T17:11:06Z","updated_at":"2018-11-29T19:10:49Z","pushed_at":"2018-12-03T23:04:56Z","git_url":"git://github.com/vangent/go-cloud.git","ssh_url":"git@github.com:vangent/go-cloud.git","clone_url":"https://github.com/vangent/go-cloud.git","svn_url":"https://github.com/vangent/go-cloud","homepage":"https://godoc.org/github.com/google/go-cloud","size":18900,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"archived":false,"open_issues_count":0,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0","node_id":"MDc6TGljZW5zZTI="},"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"google:master","ref":"master","sha":"3b5052c5344f455b19eed563cf2e026839b1339a","user":{"login":"google","id":1342004,"node_id":"MDEyOk9yZ2FuaXphdGlvbjEzNDIwMDQ=","avatar_url":"https://avatars1.githubusercontent.com/u/1342004?v=4","gravatar_id":"","url":"https://api.github.com/users/google","html_url":"https://github.com/google","followers_url":"https://api.github.com/users/google/followers","following_url":"https://api.github.com/users/google/following{/other_user}","gists_url":"https://api.github.com/users/google/gists{/gist_id}","starred_url":"https://api.github.com/users/google/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/google/subscriptions","organizations_url":"https://api.github.com/users/google/orgs","repos_url":"https://api.github.com/users/google/repos","events_url":"https://api.github.com/users/google/events{/privacy}","received_events_url":"https://api.github.com/users/google/received_events","type":"Organization","site_admin":false},"repo":{"id":126250425,"node_id":"MDEwOlJlcG9zaXRvcnkxMjYyNTA0MjU=","name":"go-cloud","full_name":"google/go-cloud","private":false,"owner":{"login":"google","id":1342004,"node_id":"MDEyOk9yZ2FuaXphdGlvbjEzNDIwMDQ=","avatar_url":"https://avatars1.githubusercontent.com/u/1342004?v=4","gravatar_id":"","url":"https://api.github.com/users/google","html_url":"https://github.com/google","followers_url":"https://api.github.com/users/google/followers","following_url":"https://api.github.com/users/google/following{/other_user}","gists_url":"https://api.github.com/users/google/gists{/gist_id}","starred_url":"https://api.github.com/users/google/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/google/subscriptions","organizations_url":"https://api.github.com/users/google/orgs","repos_url":"https://api.github.com/users/google/repos","events_url":"https://api.github.com/users/google/events{/privacy}","received_events_url":"https://api.github.com/users/google/received_events","type":"Organization","site_admin":false},"html_url":"https://github.com/google/go-cloud","description":"A library and tools for open cloud development in Go.","fork":false,"url":"https://api.github.com/repos/google/go-cloud","forks_url":"https://api.github.com/repos/google/go-cloud/forks","keys_url":"https://api.github.com/repos/google/go-cloud/keys{/key_id}","collaborators_url":"https://api.github.com/repos/google/go-cloud/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/google/go-cloud/teams","hooks_url":"https://api.github.com/repos/google/go-cloud/hooks","issue_events_url":"https://api.github.com/repos/google/go-cloud/issues/events{/number}","events_url":"https://api.github.com/repos/google/go-cloud/events","assignees_url":"https://api.github.com/repos/google/go-cloud/assignees{/user}","branches_url":"https://api.github.com/repos/google/go-cloud/branches{/branch}","tags_url":"https://api.github.com/repos/google/go-cloud/tags","blobs_url":"https://api.github.com/repos/google/go-cloud/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/google/go-cloud/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/google/go-cloud/git/refs{/sha}","trees_url":"https://api.github.com/repos/google/go-cloud/git/trees{/sha}","statuses_url":"https://api.github.com/repos/google/go-cloud/statuses/{sha}","languages_url":"https://api.github.com/repos/google/go-cloud/languages","stargazers_url":"https://api.github.com/repos/google/go-cloud/stargazers","contributors_url":"https://api.github.com/repos/google/go-cloud/contributors","subscribers_url":"https://api.github.com/repos/google/go-cloud/subscribers","subscription_url":"https://api.github.com/repos/google/go-cloud/subscription","commits_url":"https://api.github.com/repos/google/go-cloud/commits{/sha}","git_commits_url":"https://api.github.com/repos/google/go-cloud/git/commits{/sha}","comments_url":"https://api.github.com/repos/google/go-cloud/comments{/number}","issue_comment_url":"https://api.github.com/repos/google/go-cloud/issues/comments{/number}","contents_url":"https://api.github.com/repos/google/go-cloud/contents/{+path}","compare_url":"https://api.github.com/repos/google/go-cloud/compare/{base}...{head}","merges_url":"https://api.github.com/repos/google/go-cloud/merges","archive_url":"https://api.github.com/repos/google/go-cloud/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/google/go-cloud/downloads","issues_url":"https://api.github.com/repos/google/go-cloud/issues{/number}","pulls_url":"https://api.github.com/repos/google/go-cloud/pulls{/number}","milestones_url":"https://api.github.com/repos/google/go-cloud/milestones{/number}","notifications_url":"https://api.github.com/repos/google/go-cloud/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/google/go-cloud/labels{/name}","releases_url":"https://api.github.com/repos/google/go-cloud/releases{/id}","deployments_url":"https://api.github.com/repos/google/go-cloud/deployments","created_at":"2018-03-21T22:57:26Z","updated_at":"2018-12-03T22:48:00Z","pushed_at":"2018-12-03T23:04:58Z","git_url":"git://github.com/google/go-cloud.git","ssh_url":"git@github.com:google/go-cloud.git","clone_url":"https://github.com/google/go-cloud.git","svn_url":"https://github.com/google/go-cloud","homepage":"https://godoc.org/github.com/google/go-cloud","size":18875,"stargazers_count":5053,"watchers_count":5053,"language":"Go","has_issues":true,"has_projects":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":280,"mirror_url":null,"archived":false,"open_issues_count":88,"license":{"key":"apache-2.0","name":"Apache License 2.0","spdx_id":"Apache-2.0","url":"https://api.github.com/licenses/apache-2.0","node_id":"MDc6TGljZW5zZTI="},"forks":280,"open_issues":88,"watchers":5053,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/google/go-cloud/pulls/876"},"html":{"href":"https://github.com/google/go-cloud/pull/876"},"issue":{"href":"https://api.github.com/repos/google/go-cloud/issues/876"},"comments":{"href":"https://api.github.com/repos/google/go-cloud/issues/876/comments"},"review_comments":{"href":"https://api.github.com/repos/google/go-cloud/pulls/876/comments"},"review_comment":{"href":"https://api.github.com/repos/google/go-cloud/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/google/go-cloud/pulls/876/commits"},"statuses":{"href":"https://api.github.com/repos/google/go-cloud/statuses/449a128e1fbab36836b42120f2ac3c9480aa184b"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"ijt"}}