Difference between revisions of "WTP Policy on Package Visibility"

Revision as of 22:21, 12 October 2007

THIS IS A DRAFT DOCUMENT UNDER REVIEW

See bug 202711 to make comments or suggestions for improvements to this policy.

Also see the wtp-dev mailing list for some of the background and history that has lead to this proposed policy.

In contrast to the Eclipse Platform's policy of always having complete package visibility expressed in bundle's manifest.mf files, we in WTP believe there are some cases it is not necessary to require sub-projects or components to have all packages visible. We believe it may be easier and cheaper for committers to not even risk others using that sort of very internal package. On the flip side, though, there is more obligation and responsibility for committers to provide good API for any functionality that is not visible. This is simply a matter of good design ... much like the use of private variables, final classes, and packages with default (package only) java visibility. Further, we believe long term, it will be easier for clients to use our platform, since it can make clear what's API and what is not (that is, it's self documenting). Also, we hope this will improve communication between adopters and committers in that if they do need to use something that's internal, it may be that we have not well documented how to do it via API, or perhaps we have missed some requirement that we should know about.

But, to adopt this policy successfully, without impacting our work, and without impacting any adopters, there are some strict rules that have to be followed.

1. The only packages that can be made "hidden" are ones that no known adopter currently uses (known from our adopter usage scans) and that no one in WTP currently uses, even test plugins. [There may be ways for tests to use normally non-visible implementations through the use of test-time-only fragments, but that's for Eclipse Graduate school :) and will be left as an exercise for the reader.]
2. Developers should not spend a lot of time or effort making just to make things hidden, as that process itself might break our own code or adopters. The idea is to start with the easy and obvious cases and see how it goes: see how it's accepted, see how we like working with it.
3. Having package's hidden must never override the need for JUnit tests. If you can not adequately test an implementation through exposed packages, then the JUnits come first ... better to have code tested well, than to have it hidden (though, should still be marked as "x-friend").
4. If any adopter requests something be made visible, via a bugzilla entry, our inclination must always be to say "sure we will, since we are adopter friendly". In the process, we should recommend an API way to do it, if there is one, or quickly consider providing as an API. If we can do neither of those, then it will be made visible upon any reasonable request with a concrete use-case. Making a package visible in this case does not make it API, and the adopter must understand they will be broken in future releases (or even milestones) and these very internal classes will be changed as needed. There might be some legitimate deviations to this gracious flexibility, but it would require PMC review and approval. For example, there could be some cases that allowing clients access to some non-API could result in dangerous, data-loss behavior, or breaking-for-everyone-else behavior (in other words, not a reasonable request or use-case).
5. At no time should this technique be seen as a way to "force" adopters to migrate to some API, or ever have even an appearance of denying any adopter access to functionality. While researchers or individual hackers could be expected to hack up their own access rules if for some reason they wanted to access internal packages, we need to make sure no one providing products is tempted to change our access rules and redistribute our bundles with modified access rules. That would have negative consequences for the whole ecosystem.
6. For visible non-API packages, the correct use of x-friends and x-internal is still required.
7. The visibility of a package must be finalized at least one full milestone before API freeze, and most should be complete two milestones before API freeze. This is to allow reasonable time for feedback and re-considerations if adopters find a reason to make it visible by the API freeze.

Summary

To be clear, this change in policy is not an effort to make all internal classes not-visible. The policy is simply to say that it is no longer required to make everything visible. If done correctly, with good API design, no adopter would ever be effected in any way by this change in policy. While there is some risk in making this change, it is hopefully about the same level as saying that developers are free to use final classes, package visible classes, and private variables, when their code is correctly designed.

We acknowledge there is a good deal of community concern about this change in policy. We, the PMC and project leads, will closely monitor the use of this policy and we will reevaluate if there are many cases of on-going concrete problems caused.