Around last April, the topic of package
visibility was raised; that is how and when to list packages in our manifest.mf
files.Our policy then, and now, was to simply follow along the Eclipse
Platform's policy of complete visibility, as described in http://wiki.eclipse.org/Export-Package,
that is, to always list all packages in the manifest.mf file. See this
mailing list message for some of that discussion last April. http://dev.eclipse.org/mhonarc/lists/wtp-dev/msg05199.html
At that point in our development
cycle, it was too close to our 2.0 release to change what had been our
policy, for some time.
This is a good time to revisit this
issue, and decide if we in WTP should change our policy.
I think there's reasons both pro and
con, but in the end, it comes down to:
1. is it useful to us?
2. is it useful to our
clients? (adopters),
3. and (maybe) is there
a reason to be consistent between all Eclipse Projects?
[For this third question, I'll raise
this issue on the cross-project list as well ... this note is just addressed
to the WTP project].
I think if we did it in the right spirit,
carefully, slowly, incrementally, judiciously, and did not have to spend
any large effort doing it, then it could be advantageous to both, in the
long term.
The advantage to our clients is that
it makes it clearer what is very internal, and should never need to be
used/accessed by anyone, ever. In other words, it is yet another form of
clear specification of API. I think of it as similar to declaring a Class
with default (package) access so everyone else knows they should not (and
can not) use that Class. Except this is on the package to bundle level,
instead of class to package level.
I think the advantage to us developers/committers
is that it could eventually simplify our lives (and our investment
in time and energy) at least in some cases, of knowing for sure that there
would be some code we could change with no fear of impacting clients. And,
a very long term benefit, I think, is it might better motivate us to design
our code and APIs better. That is, if we knew that we had a "safe"
place to hide implementations, and only expose functions through clean
(visible) APIs, then it might both motivate us, and force us, to think
things through a bit more.
In reality, to change this policy may
not have much practical effect, at least in the near term, since it only
applies to the most internal of all the internal code. We could only "hide"
a package if it was literally never used in another plugin, even a test
plugin. There would still be tons of cases we'd have to use x-friends and
x-internal to correctly specify a non public API.
But, combined with X- friends and X-internal,
this might be yet another tool to make slow, steady progress on improving
our platform quality.
We also, as always, need to follow our
prime directive of "break no adopter", so before we changed
some visibility, we'd have to check adopter usage scans, as well as the
_entirety_ of the rest of WTP to make sure no one was using it. And, to
continue our good reputation of being adopter friendly, we'd have to be
willing to make something visible, if someone felt they really needed it,
we had no alternative, and they were willing to take the risk of being
broken in the future.
I've written a draft
WTP Policy on Package Visibility
to specify the "rules of conduct" and opened bug
202711 where people can comment
and vote on this policy, and see if we in WTP have any consensus.
In parallel, we'll query other projects,
to see what they do, and I will request that all projects must at least
have a policy, and document what it is.