Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
WTP Policy on Package Visibility
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 cases it is better for everyone not to have all packages visible, if they are truly completely internal to that one bundle. We believe it's easier and cheaper for committers to not even risk others using that sort of very internal package, and we believe it's easier for clients to use our code, since there would be less for them to look at and explore, when searching for the right API.
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.
- The only packages that can be made "hidden" are ones that no adopter currently uses 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.]
- Developers should not spend a lot of time or effort making things hidden, as that process itself might break 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.
- 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 JUnit's come first ... better to have code tested well, than to have it hidden.
- If after we start making things hidden, some 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". That is, if we can not recommend a better, API way to do it, or quickly provide as an API. Making a package visible in this case does not make it API, and the adopter must understand they will be broken in future releases, when these very internal classes change. 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.
- For visible non-API packages, the correct use of x-friends and x-internal is still required.