{"action":"created","comment":{"url":"https://api.github.com/repos/Kotlin/KEEP/pulls/comments/136610719","pull_request_review_id":60178272,"id":136610719,"diff_hunk":"@@ -0,0 +1,321 @@\n+# JSR-305 custom nullability qualifiers\n+\n+* **Type**: Design proposal\n+* **Author**: Denis Zharkov\n+* **Contributors**: Andrey Breslav, Leonid Stashevsky\n+* **Status**: Submitted\n+* **Prototype**: In progress\n+* **Discussion**: [KEEP-79](https://github.com/Kotlin/KEEP/issues/79)\n+\n+## Summary\n+\n+- Support loading more precise type information for Java declarations marked \n+with custom nullability annotations based on [JSR-305](https://jcp.org/en/jsr/detail?id=305)\n+    - Both `@TypeQualifierNickname` and `@TypeQualifierDefault` should be \n+    supported\n+- Introduce `@Migration` annotation and additional compiler flags to allow a \n+library maintainer and its users to control the way how these new annotations\n+affect the compiler's behavior. Namely, they may lead to errors, warnings on \n+usages from Kotlin or just be ignored\n+\n+## Motivation\n+\n+- It might be too verbose to annotate each signature part in a library API, so\n+`TypeQualifierDefault` is the solution. One can simply declare that all types\n+in a package are not nullable by default, and additionally annotate nullable \n+parts where it's necessary (or vice versa)\n+- The naming of default JSR-305 annotation may be rather confusing:\n+`javax.annotation.Nullable` does not actually have the same meaning as nullable\n+types in Kotlin, it only means that nullability is unknown unlike the\n+`javax.annotation.CheckForNull`. So a library maintainer may want to introduce \n+its own `Nullable` annotation as a type qualifier nickname to `CheckForNull`\n+with a more precise/clear meaning. \n+- Annotating already existing parts of a library API is a source incompatible\n+change in Kotlin, thus in some cases, it's worth migrating users smoothly:\n+    - Release a version of the library where there will be warnings on\n+    incorrect usages of the newly annotated parts\n+    - Turn these warnings into errors for the next release\n+\n+## Description\n+\n+By default all reference types from Java are perceived by the Kotlin compiler\n+as [flexible](https://github.com/JetBrains/kotlin/blob/master/spec-docs/flexible-java-types.md), \n+it means that they can be used both as nullable and not-nullable. \n+\n+In addition, Java types declarations may be annotated with some of the known \n+annotations to make them have [more precise types](https://github.com/JetBrains/kotlin/blob/master/spec-docs/flexible-java-types.md#more-precise-type-information-from-annotations)\n+when used from Kotlin. Let's call this kind of annotating as types enhancement.\n+\n+Current proposal is supposed to introduce additional ways of types enhancement\n+and instruments to control their migration status.\n+\n+### Type qualifier nicknames","path":"proposals/jsr-305-custom-nullability-qualifiers.md","position":52,"original_position":52,"commit_id":"a522ad9be4c79e0a7f1384614fef4d48ffc2a589","original_commit_id":"a522ad9be4c79e0a7f1384614fef4d48ffc2a589","user":{"login":"abreslav","id":888318,"avatar_url":"https://avatars3.githubusercontent.com/u/888318?v=4","gravatar_id":"","url":"https://api.github.com/users/abreslav","html_url":"https://github.com/abreslav","followers_url":"https://api.github.com/users/abreslav/followers","following_url":"https://api.github.com/users/abreslav/following{/other_user}","gists_url":"https://api.github.com/users/abreslav/gists{/gist_id}","starred_url":"https://api.github.com/users/abreslav/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/abreslav/subscriptions","organizations_url":"https://api.github.com/users/abreslav/orgs","repos_url":"https://api.github.com/users/abreslav/repos","events_url":"https://api.github.com/users/abreslav/events{/privacy}","received_events_url":"https://api.github.com/users/abreslav/received_events","type":"User","site_admin":false},"body":"This part is very hard to understand for people having no background in how JSR-305 is supposed to work. Given that there's no comprehensive doc on JSR-305, I think we should include a brief description of its relevant parts","created_at":"2017-09-01T16:08:04Z","updated_at":"2017-09-01T16:08:04Z","html_url":"https://github.com/Kotlin/KEEP/pull/78#discussion_r136610719","pull_request_url":"https://api.github.com/repos/Kotlin/KEEP/pulls/78","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/Kotlin/KEEP/pulls/comments/136610719"},"html":{"href":"https://github.com/Kotlin/KEEP/pull/78#discussion_r136610719"},"pull_request":{"href":"https://api.github.com/repos/Kotlin/KEEP/pulls/78"}}},"pull_request":{"url":"https://api.github.com/repos/Kotlin/KEEP/pulls/78","id":135533905,"html_url":"https://github.com/Kotlin/KEEP/pull/78","diff_url":"https://github.com/Kotlin/KEEP/pull/78.diff","patch_url":"https://github.com/Kotlin/KEEP/pull/78.patch","issue_url":"https://api.github.com/repos/Kotlin/KEEP/issues/78","number":78,"state":"open","locked":false,"title":"JSR-305 custom nullability qualifiers","user":{"login":"dzharkov","id":863207,"avatar_url":"https://avatars3.githubusercontent.com/u/863207?v=4","gravatar_id":"","url":"https://api.github.com/users/dzharkov","html_url":"https://github.com/dzharkov","followers_url":"https://api.github.com/users/dzharkov/followers","following_url":"https://api.github.com/users/dzharkov/following{/other_user}","gists_url":"https://api.github.com/users/dzharkov/gists{/gist_id}","starred_url":"https://api.github.com/users/dzharkov/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dzharkov/subscriptions","organizations_url":"https://api.github.com/users/dzharkov/orgs","repos_url":"https://api.github.com/users/dzharkov/repos","events_url":"https://api.github.com/users/dzharkov/events{/privacy}","received_events_url":"https://api.github.com/users/dzharkov/received_events","type":"User","site_admin":false},"body":"","created_at":"2017-08-14T06:14:07Z","updated_at":"2017-09-01T16:08:04Z","closed_at":null,"merged_at":null,"merge_commit_sha":"ce15ebbfe52ee58f1affe0b48a8c4c8c6d894f3e","assignee":null,"assignees":[],"requested_reviewers":[],"milestone":null,"commits_url":"https://api.github.com/repos/Kotlin/KEEP/pulls/78/commits","review_comments_url":"https://api.github.com/repos/Kotlin/KEEP/pulls/78/comments","review_comment_url":"https://api.github.com/repos/Kotlin/KEEP/pulls/comments{/number}","comments_url":"https://api.github.com/repos/Kotlin/KEEP/issues/78/comments","statuses_url":"https://api.github.com/repos/Kotlin/KEEP/statuses/a522ad9be4c79e0a7f1384614fef4d48ffc2a589","head":{"label":"Kotlin:jsr-305","ref":"jsr-305","sha":"a522ad9be4c79e0a7f1384614fef4d48ffc2a589","user":{"login":"Kotlin","id":1446536,"avatar_url":"https://avatars3.githubusercontent.com/u/1446536?v=4","gravatar_id":"","url":"https://api.github.com/users/Kotlin","html_url":"https://github.com/Kotlin","followers_url":"https://api.github.com/users/Kotlin/followers","following_url":"https://api.github.com/users/Kotlin/following{/other_user}","gists_url":"https://api.github.com/users/Kotlin/gists{/gist_id}","starred_url":"https://api.github.com/users/Kotlin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kotlin/subscriptions","organizations_url":"https://api.github.com/users/Kotlin/orgs","repos_url":"https://api.github.com/users/Kotlin/repos","events_url":"https://api.github.com/users/Kotlin/events{/privacy}","received_events_url":"https://api.github.com/users/Kotlin/received_events","type":"Organization","site_admin":false},"repo":{"id":54388526,"name":"KEEP","full_name":"Kotlin/KEEP","owner":{"login":"Kotlin","id":1446536,"avatar_url":"https://avatars3.githubusercontent.com/u/1446536?v=4","gravatar_id":"","url":"https://api.github.com/users/Kotlin","html_url":"https://github.com/Kotlin","followers_url":"https://api.github.com/users/Kotlin/followers","following_url":"https://api.github.com/users/Kotlin/following{/other_user}","gists_url":"https://api.github.com/users/Kotlin/gists{/gist_id}","starred_url":"https://api.github.com/users/Kotlin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kotlin/subscriptions","organizations_url":"https://api.github.com/users/Kotlin/orgs","repos_url":"https://api.github.com/users/Kotlin/repos","events_url":"https://api.github.com/users/Kotlin/events{/privacy}","received_events_url":"https://api.github.com/users/Kotlin/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Kotlin/KEEP","description":"Kotlin Evolution and Enhancement Process","fork":false,"url":"https://api.github.com/repos/Kotlin/KEEP","forks_url":"https://api.github.com/repos/Kotlin/KEEP/forks","keys_url":"https://api.github.com/repos/Kotlin/KEEP/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Kotlin/KEEP/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Kotlin/KEEP/teams","hooks_url":"https://api.github.com/repos/Kotlin/KEEP/hooks","issue_events_url":"https://api.github.com/repos/Kotlin/KEEP/issues/events{/number}","events_url":"https://api.github.com/repos/Kotlin/KEEP/events","assignees_url":"https://api.github.com/repos/Kotlin/KEEP/assignees{/user}","branches_url":"https://api.github.com/repos/Kotlin/KEEP/branches{/branch}","tags_url":"https://api.github.com/repos/Kotlin/KEEP/tags","blobs_url":"https://api.github.com/repos/Kotlin/KEEP/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Kotlin/KEEP/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Kotlin/KEEP/git/refs{/sha}","trees_url":"https://api.github.com/repos/Kotlin/KEEP/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Kotlin/KEEP/statuses/{sha}","languages_url":"https://api.github.com/repos/Kotlin/KEEP/languages","stargazers_url":"https://api.github.com/repos/Kotlin/KEEP/stargazers","contributors_url":"https://api.github.com/repos/Kotlin/KEEP/contributors","subscribers_url":"https://api.github.com/repos/Kotlin/KEEP/subscribers","subscription_url":"https://api.github.com/repos/Kotlin/KEEP/subscription","commits_url":"https://api.github.com/repos/Kotlin/KEEP/commits{/sha}","git_commits_url":"https://api.github.com/repos/Kotlin/KEEP/git/commits{/sha}","comments_url":"https://api.github.com/repos/Kotlin/KEEP/comments{/number}","issue_comment_url":"https://api.github.com/repos/Kotlin/KEEP/issues/comments{/number}","contents_url":"https://api.github.com/repos/Kotlin/KEEP/contents/{+path}","compare_url":"https://api.github.com/repos/Kotlin/KEEP/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Kotlin/KEEP/merges","archive_url":"https://api.github.com/repos/Kotlin/KEEP/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Kotlin/KEEP/downloads","issues_url":"https://api.github.com/repos/Kotlin/KEEP/issues{/number}","pulls_url":"https://api.github.com/repos/Kotlin/KEEP/pulls{/number}","milestones_url":"https://api.github.com/repos/Kotlin/KEEP/milestones{/number}","notifications_url":"https://api.github.com/repos/Kotlin/KEEP/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Kotlin/KEEP/labels{/name}","releases_url":"https://api.github.com/repos/Kotlin/KEEP/releases{/id}","deployments_url":"https://api.github.com/repos/Kotlin/KEEP/deployments","created_at":"2016-03-21T12:54:23Z","updated_at":"2017-09-01T07:48:05Z","pushed_at":"2017-08-31T11:08:47Z","git_url":"git://github.com/Kotlin/KEEP.git","ssh_url":"git@github.com:Kotlin/KEEP.git","clone_url":"https://github.com/Kotlin/KEEP.git","svn_url":"https://github.com/Kotlin/KEEP","homepage":null,"size":233,"stargazers_count":478,"watchers_count":478,"language":null,"has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":33,"mirror_url":null,"open_issues_count":36,"forks":33,"open_issues":36,"watchers":478,"default_branch":"master"}},"base":{"label":"Kotlin:master","ref":"master","sha":"745ef12e2940649f515d966ba6e94b8494e76bf6","user":{"login":"Kotlin","id":1446536,"avatar_url":"https://avatars3.githubusercontent.com/u/1446536?v=4","gravatar_id":"","url":"https://api.github.com/users/Kotlin","html_url":"https://github.com/Kotlin","followers_url":"https://api.github.com/users/Kotlin/followers","following_url":"https://api.github.com/users/Kotlin/following{/other_user}","gists_url":"https://api.github.com/users/Kotlin/gists{/gist_id}","starred_url":"https://api.github.com/users/Kotlin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kotlin/subscriptions","organizations_url":"https://api.github.com/users/Kotlin/orgs","repos_url":"https://api.github.com/users/Kotlin/repos","events_url":"https://api.github.com/users/Kotlin/events{/privacy}","received_events_url":"https://api.github.com/users/Kotlin/received_events","type":"Organization","site_admin":false},"repo":{"id":54388526,"name":"KEEP","full_name":"Kotlin/KEEP","owner":{"login":"Kotlin","id":1446536,"avatar_url":"https://avatars3.githubusercontent.com/u/1446536?v=4","gravatar_id":"","url":"https://api.github.com/users/Kotlin","html_url":"https://github.com/Kotlin","followers_url":"https://api.github.com/users/Kotlin/followers","following_url":"https://api.github.com/users/Kotlin/following{/other_user}","gists_url":"https://api.github.com/users/Kotlin/gists{/gist_id}","starred_url":"https://api.github.com/users/Kotlin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kotlin/subscriptions","organizations_url":"https://api.github.com/users/Kotlin/orgs","repos_url":"https://api.github.com/users/Kotlin/repos","events_url":"https://api.github.com/users/Kotlin/events{/privacy}","received_events_url":"https://api.github.com/users/Kotlin/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/Kotlin/KEEP","description":"Kotlin Evolution and Enhancement Process","fork":false,"url":"https://api.github.com/repos/Kotlin/KEEP","forks_url":"https://api.github.com/repos/Kotlin/KEEP/forks","keys_url":"https://api.github.com/repos/Kotlin/KEEP/keys{/key_id}","collaborators_url":"https://api.github.com/repos/Kotlin/KEEP/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/Kotlin/KEEP/teams","hooks_url":"https://api.github.com/repos/Kotlin/KEEP/hooks","issue_events_url":"https://api.github.com/repos/Kotlin/KEEP/issues/events{/number}","events_url":"https://api.github.com/repos/Kotlin/KEEP/events","assignees_url":"https://api.github.com/repos/Kotlin/KEEP/assignees{/user}","branches_url":"https://api.github.com/repos/Kotlin/KEEP/branches{/branch}","tags_url":"https://api.github.com/repos/Kotlin/KEEP/tags","blobs_url":"https://api.github.com/repos/Kotlin/KEEP/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/Kotlin/KEEP/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/Kotlin/KEEP/git/refs{/sha}","trees_url":"https://api.github.com/repos/Kotlin/KEEP/git/trees{/sha}","statuses_url":"https://api.github.com/repos/Kotlin/KEEP/statuses/{sha}","languages_url":"https://api.github.com/repos/Kotlin/KEEP/languages","stargazers_url":"https://api.github.com/repos/Kotlin/KEEP/stargazers","contributors_url":"https://api.github.com/repos/Kotlin/KEEP/contributors","subscribers_url":"https://api.github.com/repos/Kotlin/KEEP/subscribers","subscription_url":"https://api.github.com/repos/Kotlin/KEEP/subscription","commits_url":"https://api.github.com/repos/Kotlin/KEEP/commits{/sha}","git_commits_url":"https://api.github.com/repos/Kotlin/KEEP/git/commits{/sha}","comments_url":"https://api.github.com/repos/Kotlin/KEEP/comments{/number}","issue_comment_url":"https://api.github.com/repos/Kotlin/KEEP/issues/comments{/number}","contents_url":"https://api.github.com/repos/Kotlin/KEEP/contents/{+path}","compare_url":"https://api.github.com/repos/Kotlin/KEEP/compare/{base}...{head}","merges_url":"https://api.github.com/repos/Kotlin/KEEP/merges","archive_url":"https://api.github.com/repos/Kotlin/KEEP/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/Kotlin/KEEP/downloads","issues_url":"https://api.github.com/repos/Kotlin/KEEP/issues{/number}","pulls_url":"https://api.github.com/repos/Kotlin/KEEP/pulls{/number}","milestones_url":"https://api.github.com/repos/Kotlin/KEEP/milestones{/number}","notifications_url":"https://api.github.com/repos/Kotlin/KEEP/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/Kotlin/KEEP/labels{/name}","releases_url":"https://api.github.com/repos/Kotlin/KEEP/releases{/id}","deployments_url":"https://api.github.com/repos/Kotlin/KEEP/deployments","created_at":"2016-03-21T12:54:23Z","updated_at":"2017-09-01T07:48:05Z","pushed_at":"2017-08-31T11:08:47Z","git_url":"git://github.com/Kotlin/KEEP.git","ssh_url":"git@github.com:Kotlin/KEEP.git","clone_url":"https://github.com/Kotlin/KEEP.git","svn_url":"https://github.com/Kotlin/KEEP","homepage":null,"size":233,"stargazers_count":478,"watchers_count":478,"language":null,"has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":33,"mirror_url":null,"open_issues_count":36,"forks":33,"open_issues":36,"watchers":478,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/Kotlin/KEEP/pulls/78"},"html":{"href":"https://github.com/Kotlin/KEEP/pull/78"},"issue":{"href":"https://api.github.com/repos/Kotlin/KEEP/issues/78"},"comments":{"href":"https://api.github.com/repos/Kotlin/KEEP/issues/78/comments"},"review_comments":{"href":"https://api.github.com/repos/Kotlin/KEEP/pulls/78/comments"},"review_comment":{"href":"https://api.github.com/repos/Kotlin/KEEP/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/Kotlin/KEEP/pulls/78/commits"},"statuses":{"href":"https://api.github.com/repos/Kotlin/KEEP/statuses/a522ad9be4c79e0a7f1384614fef4d48ffc2a589"}},"author_association":"COLLABORATOR"}}
{"actor":{"display_login":"abreslav"}}