{"action":"created","issue":{"url":"https://api.github.com/repos/gradle/gradle/issues/541","labels_url":"https://api.github.com/repos/gradle/gradle/issues/541/labels{/name}","comments_url":"https://api.github.com/repos/gradle/gradle/issues/541/comments","events_url":"https://api.github.com/repos/gradle/gradle/issues/541/events","html_url":"https://github.com/gradle/gradle/pull/541","id":115388474,"number":541,"title":"Refactor API jar generation","user":{"login":"cbeams","id":301810,"avatar_url":"https://avatars.githubusercontent.com/u/301810?v=3","gravatar_id":"","url":"https://api.github.com/users/cbeams","html_url":"https://github.com/cbeams","followers_url":"https://api.github.com/users/cbeams/followers","following_url":"https://api.github.com/users/cbeams/following{/other_user}","gists_url":"https://api.github.com/users/cbeams/gists{/gist_id}","starred_url":"https://api.github.com/users/cbeams/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cbeams/subscriptions","organizations_url":"https://api.github.com/users/cbeams/orgs","repos_url":"https://api.github.com/users/cbeams/repos","events_url":"https://api.github.com/users/cbeams/events{/privacy}","received_events_url":"https://api.github.com/users/cbeams/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2015-11-05T22:20:46Z","updated_at":"2015-11-06T04:53:10Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/gradle/gradle/pulls/541","html_url":"https://github.com/gradle/gradle/pull/541","diff_url":"https://github.com/gradle/gradle/pull/541.diff","patch_url":"https://github.com/gradle/gradle/pull/541.patch"},"body":"This series of commits refines and restructures the implementation of\r\nAPI member selection and extraction and the subsequent assembly of an\r\n`ApiJar` based on that content.\r\n\r\nThese changes are being submitted as a pull request for several reasons,\r\nbut primary among them is to prompt a discussion about the future\r\norganization and structure of the Gradle codebase. To this end, please\r\nread the first five commit messages in this PR (particularly the fifth). For\r\nconvenience, here they are in order:\r\n\r\n 1. f216da1dde85e265d11c899f1ecf3914e5efc78a\r\n 2. 17663638b7be27d68731f09cb344fe59b3332ea2\r\n 3. 81837af6325f06bcc0e746fa358508a683824a6b\r\n 4. 417b36d24174f049304c40a5d0ddb87d93e99915\r\n 5. a37a3ef90bc4b56355c48df56d9aee9e3ac9bf95\r\n\r\nTogether, these commits make a case for careful package design and\r\nplacement, and in particular make a case for the use of package-private\r\nvisibility as a mechanism for reducing the surface area of our own\r\npublic API. In conjunction with our `@Incubating` annotation, better\r\npackaging and visibility management can perhaps help us move away from\r\nover-reliance on \"internal\" package techniques.\r\n\r\nPackage-private visibility is not a panacea and these commits don't\r\nintend to make that case. Rather they suggest that we treat it as an\r\nimportant tool in helping us evolve our public API, manage compatibility\r\nconcerns, and so on.\r\n\r\nThe remainder of the commits in this PR are also intended to be read in\r\norder, but in the somewhat more focused context of a code review of the\r\nAPI jar generation feature itself.\r\n\r\nBarring any particular objections, this PR will be merged tomorrow\r\n(Friday) after discussion with the original authors of the code that's\r\nbeen refactored here. Again, the PR itself exists primarily as a means\r\nof raising awareness about these ideas and a place to discuss them in\r\ncontext."},"comment":{"url":"https://api.github.com/repos/gradle/gradle/issues/comments/154285394","html_url":"https://github.com/gradle/gradle/pull/541#issuecomment-154285394","issue_url":"https://api.github.com/repos/gradle/gradle/issues/541","id":154285394,"user":{"login":"bigdaz","id":179734,"avatar_url":"https://avatars.githubusercontent.com/u/179734?v=3","gravatar_id":"","url":"https://api.github.com/users/bigdaz","html_url":"https://github.com/bigdaz","followers_url":"https://api.github.com/users/bigdaz/followers","following_url":"https://api.github.com/users/bigdaz/following{/other_user}","gists_url":"https://api.github.com/users/bigdaz/gists{/gist_id}","starred_url":"https://api.github.com/users/bigdaz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bigdaz/subscriptions","organizations_url":"https://api.github.com/users/bigdaz/orgs","repos_url":"https://api.github.com/users/bigdaz/repos","events_url":"https://api.github.com/users/bigdaz/events{/privacy}","received_events_url":"https://api.github.com/users/bigdaz/received_events","type":"User","site_admin":false},"created_at":"2015-11-06T04:53:10Z","updated_at":"2015-11-06T04:53:10Z","body":"I'm also -1 on using package privacy for internal classes. I think we give\nup more than we gain. I'd be +1 for more consistency with how we structure\nour internal packages.\nI strongly recommend not making this change without explicit go ahead from\nAdam.\n\nOn Thu, 5 Nov 2015, 3:51 p.m. Cédric Champeau <notifications@github.com>\nwrote:\n\n> I have no strong objection on the renames (in fact, there is a difference\n> between allowed and exported: allowed packages are not necessarily the same\n> as exported ones. Take the example of the java-base module. It is actually\n> surprising that no test fails after removing JavaBaseModule, because it\n> is used in validation).\n>\n> As for package private classes, I am -1 on this. I don't like this\n> mechanism. For me package privacy is broken. Should have it been inherited\n> by sub-packages, or through class hierarchy (A in package pkg1, B extends A\n> in pkg2, C extends A in pkg1), I would have maybe a different thinking.\n>\n> But I *really* like the separation of internal package. It gives a lot of\n> flexibility, and it is actually what is going to be publicized with Jigsaw\n> modules. I am not sure we're not moving in the right direction doing this.\n> In general, I consider that almost all types can be public, and it should\n> be documented when to use or not to use one class. In particular, users\n> might want to use internal classes. I did it in the past, and the fact that\n> it's in a package named \"internal\" makes you aware that it might be broken\n> in the future, but you are aware. On the other hand, if it had been package\n> private, I wouldn't be able to do it, or I would just have worked around it\n> using a class in the same package. Which is dirty.\n>\n> Last but not least, @Incubating in Gradle has a tradition of saying \"it's\n> an experimental API\". Yet, they belong to the public API. I don't remember\n> any class marked as @Incubating which has been removed. On the other\n> hand, I feel ok to remove, rename or move a class in an internal package.\n> And as soon as it moves into a package that doesn't contain internal, to\n> me, it becomes public API.\n>\n> —\n> Reply to this email directly or view it on GitHub\n> <https://github.com/gradle/gradle/pull/541#issuecomment-154221212>.\n>\n"}}