Re: [wtp-dev] Ever wanted to be invisible?

[Tim deBoer <deboer@xxxxxxxxxx>]

Hi Max,

Server tools was one of the first components
in WTP to declare API, and we try to expand it every release as necessary.
I see only 2 API requests from redhat & JBoss, which seems a far cry
from 'everything that uses servers will need internal packages'. Please
ensure that you are opening bugs for internal usage so that we can try
to improve the situation.

Thanks,
Tim deBoer
deboer@xxxxxxxxxx

Max Rydahl Andersen <max.andersen@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

09/12/2007 05:08 AM

Please respond to
"General discussion of project-wide or architectural issues."        <wtp-dev@xxxxxxxxxxx>

To	"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc
Subject	Re: [wtp-dev] Ever wanted to be invisible?

I fully agree....I know the first long list of projects that would not
work if usage of WTP internal packages where programmatically prohibited.

e.g. everything that uses the server and xml editing API...

/max

> In theory I like the idea of strict package structure, but the problem
> with eclipse in general is that often times very few people are engaged
> in the creation of the API, or even listen in to the conference calls
> regarding its creation. Defects are only brought out later, as new
> adopters begin using it, and API changes / expansions usually if not
> always have to wait until the next major release so that they don't
> break those adopters already using it.
> 
> When starting new projects I believe strict API is ok, but as long
as 
> you can't change API between minor releases, following strict API
will 
> be much more difficult for adopters to even use what's there and get
> involved in the short term, even if in an undesired fashion. They'll
> have to wait for the next release, which could even discourage adopters
> from jumping onboard if the wait is going to be too long.
> 
> - Rob Stryker
> 
> Scott Rich wrote:
>>
>> I'll thrown in my two cents.  The Jazz project started out
of the gate 
>> using strict visibility.  As a platform, this has been a
real 
>> "game-changer".  The API contract is much more
real because it's being 
>> enforced by the compiler.  We do negotiate x-friends, but
it's almost 
>> exclusively for testing, we only have a small handful of runtime
>> friends, and even those we feel guilty about and we know that
they 
>> point out architectural issues.  Because of the limited visibility,
>> we've been able to do dramatic replacements of platform component
>> implementations with minimal disruption.  It really works
as 
>> advertised...
>>
>> I definitely recommend WTP look into minimizing visibility.  You've
>> already got reasonable .internal package structure, right? 
>> Scott
>>
>> ---------------------------------------------------------------
>> Scott Rich
>> Senior Technical Staff Member
>> Jazz Server Development
>> (919) 254-1943 (tieline 444)
>> srich@xxxxxxxxxx
>>
>>
>>
>>
>> *David M Williams/Raleigh/IBM@IBMUS*
>> Sent by: wtp-dev-bounces@xxxxxxxxxxx
>>
>> 09/08/2007 04:24 AM
>> Please respond to
>> "General discussion of project-wide or architectural issues."
      
>>  <wtp-dev@xxxxxxxxxxx>
>>
>>
>>     
>> To
>>     wtp-dev@xxxxxxxxxxx
>> cc
>>     
>> Subject
>>     [wtp-dev] Ever wanted to be invisible?
>>
>>
>>
>>     
>>
>>
>>
>>
>>
>>
>> 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_ 
>> <http://wiki.eclipse.org/WTP_Policy_on_Package_Visibility>
to specify 
>> the "rules of conduct" and opened _bug 202711_ 
>> <https://bugs.eclipse.org/bugs/show_bug.cgi?id=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.
>>
>>
>>
>> _______________________________________________
>> wtp-dev mailing list
>> wtp-dev@xxxxxxxxxxx
>> https://dev.eclipse.org/mailman/listinfo/wtp-dev
>>
>> ------------------------------------------------------------------------
>>
>> _______________________________________________
>> wtp-dev mailing list
>> wtp-dev@xxxxxxxxxxx
>> https://dev.eclipse.org/mailman/listinfo/wtp-dev
>>   
> 
> _______________________________________________
> wtp-dev mailing list
> wtp-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/wtp-dev

_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev