Difference between revisions of "WTP Policy on Package Visibility"

From Eclipsepedia

Jump to: navigation, search
(added bugzilla)
(added link to mailing list msg)
Line 3: Line 3:
 
See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=202711 bug 202711] to make  
 
See [https://bugs.eclipse.org/bugs/show_bug.cgi?id=202711 bug 202711] to make  
 
comments or suggestions for improvements to this policy.  
 
comments or suggestions for improvements to this policy.  
 +
 +
Also see the [http://dev.eclipse.org/mhonarc/lists/wtp-dev/msg05599.html wtp-dev mailing list] for some of the background and history that has lead to this proposed policy.
 +
 
<hr />
 
<hr />
 
In contrast to the [http://wiki.eclipse.org/Export-Package 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.  
 
In contrast to the [http://wiki.eclipse.org/Export-Package 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.  

Revision as of 04:38, 8 September 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 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.

  1. 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.]
  2. 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.
  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 JUnit's come first ... better to have code tested well, than to have it hidden.
  4. 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.
  5. For visible non-API packages, the correct use of x-friends and x-internal is still required.