RE: [cross-project-issues-dev] Is everyone always visible?

[Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>]

I read it but did not find anything
in there compelling :-) 

Some comments

> "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 first part of this sentence does
not jive with the "not spend large effort".  At the very
least this will be a distraction.  If it is only done in a few places
then it won't be much effort but it also will not be of much value and
will end up being more confusing because it is another kind of thing/concept.

> is it useful to our clients? (adopters),

There is not much here that tooling
cannot (and for the most part already does) give you.  Imagine that
you had a "show me only API" button in the Java views similar
to the "show me only public classes". see http://wiki.eclipse.org/PDE_UI_Incubator_ApiTools

> if they are truly completely internal

Seems hard and contentious to define
"truly"

> 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. 
This appears to implicitly introduce
a third type of code.  API, not-API and "stuff that you shouldn't
use but if you must"...  That is, currently the model is API
and not-API (i.e., x-internal).  By further "hard-hiding"
some things there is an implication that the "x-internal" stuff
is less internal than the hidden stuff.  That, IMHO, weakens the "internal"
statement and muddies the waters

>  knowing for sure that there
would be some code we could change with no fear of impacting clients.
Yes, this would be good.  To a
certain degree the API tooling will help address this with krugle-like
searches.  That will not be perfect but will be a start

> it might better motivate us to
design our code and APIs better.
This does not seem clear.  Internal
is internal and not intended to be used by others.  API is available
to others.  In the platform we are seeing an increasing need for "SPI"
but that is a different topic.

> 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
pragmatically you will not be able to
detect all adopters uses.  Are you going to analyze the IBM, BEA,
... products?

> some adopter requests something
be made visible
As was pointed out in another post,
this is often long after the fact.  Perhaps even after the release.

> I'm curious ... those of you that
feel so strongly about this ... do you think all Classes should be public?

> And we should no longer use "protected"
or default (package) access for Classes? I'm wondering what you think 
> is different about this proposal
I'm making, and those cases? 
This issue really only comes up in API
packages.  For the most part these packages contain only public types.
 There may be cases of protected fields/methods but they would be
rare.  Default/package and private visibility are very rarely used
in these packages and only where we are forced to because of some coding
complexity.  I understand you point here and basically agree.  For
internal packages we tend to have public classes all around.

> Are "we" just old fashioned,
stuck in our ways, and missing out on a innovations that have occurred
in improving specifications? 
I agree that it is worthwhile and
healthy to revisit these issues from time to time.

So in the end there just does not seem
to be any conpelling evidence that this is an advance and there is clear
evidence that the approach has non-trivial issues.

Jeff

David M Williams <david_williams@xxxxxxxxxx>
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

09/10/2007 01:00 AM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>
cc
Subject	RE: [cross-project-issues-dev] Is everyone always visible?

Oh, I love being controversial :) 

So, I'll say that so far, all these strong opinions haven't said anything
to change my mind. 

Mostly because I can tell you haven't read the proposed policy or any of
the background mailing list links :) 

This isn't about making an effort to hide internals. This is about not
strictly requiring everyone to _always_ list everything 
in the manifest.mf file.  We in WTP are fully aware almost all of
our simply "internals" would still have to be listed, 
but that's not what this is about. I think any package we decided fit within
our policy would not be missed by anyone. 
(If it was, we failed at implementing our policy!). 

I'm curious ... those of you that feel so strongly about this ... do you
think all Classes should be public? And we should 
no longer use "protected" or default (package) access for Classes?
I'm wondering what you think is different about this 
proposal I'm making, and those cases? Are "we" just old fashioned,
stuck in our ways, and missing out on a innovations that have occurred
in improving specifications?

Jeff McAffer <Jeff_McAffer@xxxxxxxxxx>
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

09/09/2007 10:34 PM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>
cc
Subject	RE: [cross-project-issues-dev] Is everyone always visible?

It just wouldn't be September without this topic coming up...  Guess
it is David's turn to get slapped around a bit...  ;-)

I am firmly with Chris and Mik.  Many years ago I proposed something
much along the lines of what you are suggesting. The out-pouring was quite
dramatic.  Then a couple years ago someone misunderstood something
I said for such a proposal.  It took about a month of email to calm
that one down. 

In the end the "winning" argument is that without exporting of
some kind, people just cannot access the code.  Where is the win in
that?  The PDE/JDT folks have done a wonderful job of tooling x-internal
and x-friends.  The upcoming API tooling will enhance this by allowing
for postmortem and third-party API/internal usage analysis.  Further
more, you can run the platform in "strict" mode and get the effect
you are looking for.  With all these mechanisms, people do not have
any excuse for using non-API other than "we thought long and hard
and really needed to call that method, access that class, ..."  As
open source bundle producers our job is to inform our users of the API
and intended use models.  For the most part the consumers are adults
who can choose for themselves if they want to color outside the lines.
  

Since the decision is so black and white, pursuing this direction will
also require considerable effort and debate within the community as you
decide which code to export and which to banish. 

Chris' point about the code being freely available and modifiable is bang
on as well.  All this would do in the end is force people to fork
*your* bundle to add the export.  We'd have a configuration nightmare.

Finally, rightly or wrongly, there are quite a number of commercial products
(some you know all too well) that use internals.  Who is to say that
the code you are looking to banish would not be the subject of such wandering
eyes? 

In short, just say "no" 

Jeff

"Mik Kersten" <beatmik@xxxxxxx>
Sent by: cross-project-issues-dev-bounces@xxxxxxxxxxx

09/09/2007 08:53 PM

Please respond to
Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>

To	"'Cross project issues'" <cross-project-issues-dev@xxxxxxxxxxx>
cc
Subject	RE: [cross-project-issues-dev] Is everyone always visible?

I very strongly agree with the points that Chris raises.
 
As someone who has to evolve and maintain an API, I wholeheartedly sympathize
with the desire to hide some of the internals that can make a framework
fragile or result in a burden when integrators complain about changing
internals.  But in my opinion the benefits to integrators far outweigh
the relatively small burden to the project.  Those building APIs can
never predict all the interesting ways that their framework will get extended,
which is why access to internals has been such a key enabler of extensibility
for the Platform.  By being at the bottom of the stack the Platform
exposes itself to more of a maintenance burden more than any other project,
and they have done an amazing job leading by example, and putting safeguards
in place when needed.  The following blog post has a summary of why
I think it’s so important to have access to all of the code in an open
framework: http://tasktop.com/blog/?p=5
  
 
As a practical matter, for our 3.0 cycle Mylyn is planning to better support
JEE development via WTP-specific extensions, such as those already prototyped
in Spring IDE.  The Mylyn Platform/SDK extensions could not exist
if any of the SDK had inaccessible internals, even those that the API developers
thought nobody would ever want to access.  This is because Mylyn is
an extension that crosscuts typical API boundaries by layering over the
tools entire UI and models beneath that UI.  If WTP starts hiding
packages this would either preclude or severely limit the Mylyn integration
for WTP, and we would get stuck doing exactly the “crazy stuff” that
Chris is referring to. 
 
Mik 
 
 
From: cross-project-issues-dev-bounces@xxxxxxxxxxx [mailto:cross-project-issues-dev-bounces@xxxxxxxxxxx]
On Behalf Of Chris Aniszczyk
Sent: Saturday, September 08, 2007 1:59 PM
To: Cross project issues
Subject: Re: [cross-project-issues-dev] Is everyone always visible?

I don't think this is a good idea personally. WTP isn't a commercial product, it's an open source project. The community expects that they can access any code, internal or not. If you prevent them from accessing certain classes, they'll do crazy stuff like Equinox Transforms (http://wiki.eclipse.org/Equinox_Transforms) to get the MANIFEST.MF the way they like it.

My inclination is no to the change especially since this is going from a "everything open come join the party" to "something things are closed" model.

After reading your policy, how will you implement #1? It seems this would only be possible for future packages.
"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..."



In response to what other projects do, I think that's a fantastic idea to document how other projects treat API (although most I believe will follow the traditional Platform model)

Cheers,

---
Chris Aniszczyk | IBM Lotus | Eclipse Committer | http://mea-bloga.blogspot.com | +1.860.839.2465

David M Williams---09/08/2007 04:26:09 AM---As philosophical as that sounds ... I really am asking about Java code. :) I hope everyone knows

From:	David M Williams/Raleigh/IBM@IBMUS
To:	Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>
Date:	09/08/2007 04:26 AM
Subject:	[cross-project-issues-dev] Is everyone always visible?

---

As philosophical as that sounds ... I really am asking about Java code.
:) 

I hope everyone knows that package visibility outside it's bundle is controlled
by whether it is listed in the manifest.mf file. 

Historically, we in WTP have followed the Eclipse
Platform's policy of
always making every package visible to others, even if it was 
not API and even if it really was never used any where else. But, now we
in WTP are considering
to change our policy,
to allow some 
packages to be hidden, if they really are completely internal. We see this
potentially as an improved way to specify API's, along with 
the usual correct use of x-internal, x-friend, etc. And also, we hope it
will motivate us to be more careful in our future code and designs to 
better separate API from implementation. 

So, two things came to mind: 

1. What do other projects do?, and 

2. Would it be useful to request each project in Ganymede to document their
policy? 

To address both these questions, I've started Ganymede_Policies_on_Package_Visibility
as a place where Projects 
can specify, and link to, their written policy on the matter. 

So, if you would please, take a minute and fill in the tables listed there,
if you think it would be useful. 
I created the table assuming each top level project would have one policy,
and that it would not differ from component to 
component ... so, that's another thing ... let me know if that's an incorrect
assumption. 

And, by all means, respond here if you have strong feelings about what
a project's policy should be. 
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
cross-project-issues-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev