Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[wtp-dev] Re: Ever wanted to be invisible? 
All,
Since we have a bug report for gathering comments, I have placed mine there. I encourage everyone else to do the same, as David requested, so we have an appropriate record of the discussion around this proposed change. 

Bug report: https://bugs.eclipse.org/bugs/show_bug.cgi?id=202711

Regards,
Todd
----- Original Message ----- From: "Max Rydahl Andersen" <max.andersen@xxxxxxxxxx> To: "General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx> 
Sent: Wednesday, September 12, 2007 9:10 AM
Subject: [work] Re: [wtp-dev] Ever wanted to be invisible?
Don't think I don't agree on the intent of this suggested change, but putting this request in the light of the reality of...
a) API not maturing for certain highly used components (like the XML editor and model) even though it is probably one of the most adopted WTP codebase i've seen around
b) if the tendency of only doing api fixes/additions in major releases continues a hard invisibility of code prevents me (as an adopter which have *different* release schedules) to do workarounds (without forking!)
If this invisible flag would be enabled (but overridable) by default for builds and disabled by default at runtime I would probably be fine....since then I would still provide workarounds.
Note: I hate the fact that I have to depend on any *internal* package in eclipse but it is just a fact of life that it is relevant to be productive and provide real value on top ....and I/we do try to create bugreports for every usage of it. 

/max


It's a self-worsening problem. Since internal api is easily accessible,
two things happen: (a) people don't file api request bugs when forced to
use internal api and (b) there is no pressure on the committers who own
the particular code to create actual api and remove usage of internal
code. This problem is worsened by the desire to not break adopters
unnecessarily, even if the change is in internal code. This means that
adopters don't feel the pressure to do (a) or to insist on (b). The
Eclipe Platform team, where the "open internals" policy originated,
don't think twice about making changes in the internals. This puts
pressure on platform users to look for an api-based solution or to do
the (a)/(b) thing since they don't want to be continually fixing
breakages. With WTP, on the other hand, people feel safe using internal
code.

I am not sure that there is a one-fits-all solution here (especially for
an existing code base). Certain internal packages are truly internal and
no-one has any need to use time. The policy should allow those packages
to not be exported. Certain internal packages have fair amount of code
that might need to be made API, but hasn't been yet. Those will need to
be kept accessible until api has been fleshed out. This is also an
indicator of a component's maturity. IMHO, any component that feels
compelled to export it's internal code in order to allow
consumers/adopters to implement certain function has not reached API
maturity. Regarding the comment of how we would handle adopters stumbling on 
something they need in an non-exported internal package... The first
thing that should happen is a bug. That allows committers to see what
you are trying to do and determine whether (a) there exists an api way
of doing this (this happens a lot), (b) the adopter is trying to do
something very unreasonable and no api will likely be ever created to
support this usage (this does happen), or (c) this is really an api
outtage. For (c), while it is true that api changes in service releases
are technically disallowed, we've certainly have broken that policy
repeatedly in the past to satisfy api requests in cases where there is
urgent need and changes are additive. There is also always the
possibility of going ahead and exporting the package in question as
x-internal until appropriate api can be created. I don't think there is
any issue with exporting a previously not exported package in a service
release.

- Konstantin

 -----Original Message-----
From: wtp-dev-bounces@xxxxxxxxxxx [mailto:wtp-dev-bounces@xxxxxxxxxxx]
On Behalf Of Max Rydahl Andersen
Sent: Wednesday, September 12, 2007 2:09 AM
To: General discussion of project-wide or architectural issues.
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
Notice: This email message, together with any attachments, may contain information of BEA Systems, Inc., its subsidiaries and affiliated entities, that may be confidential, proprietary, copyrighted and/or legally privileged, and is intended solely for the use of the individual or entity named in this message. If you are not the intended recipient, and have received this message in error, please immediately return this by email and then delete it. 
_______________________________________________
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

Back to the top