[wtp-pmc] Comments on WTP API Policy

[David M Williams <david_williams@xxxxxxxxxx>]

As agreed in PMC Meeting, here's my
comments on

http://wiki.eclipse.org/WTP_API_Policy

Declared API

"must be reviewed by the component lead. "

Should that be "reviewed and approved"?

Should that be "(sub) project lead"
now? Or, at least, 
either-or? Such as 
"must be reviewed and approved by the component or subproject lead".


Also, in this section, there's no mention
of clients. I think that's a good guide the eclipse platform has advocated.

I'd like you to add something like 

"Declared API must have at least
two clients, at least one of which must be public as part of WTP (or another
Eclipse Project). 
Note, in some cases, it's fine if the
client is an example, or sample, instead of full fledged end-user functionality."




Provisional API

This is the section I disagree with.
While we currently have provisional API, I don't think we should add any
additional. 
If we do new work, it should be done
as API. If we can't accomplish the API work in a release cycle, then we
shouldn't do it. 

Part of my reasoning is that we've developed
a climate of developers being over-cautious on declaring API. I'd like
to change that. 

And, my main concern with this is a
business one. From both ends. If "we" do some "partial"
work, there's no guarantee "we" would still be there the following
cycle to finish the API, or decide it's a high priority to finish. Similar
from clients end ... in my experience, most clients want to write something
once, and while they will point out problems, they won't really provide
"feedback on the API" ... so, my thinking is, if it's good enough
for two clients, and has had at least some review (such as by at least
project or component lead) then it's not going to get very much better.

(And, sure, people may want enhancements,
etc., but those are rarely breaking ... and, if it is breaking, then should
be done as new work, new API, etc). 

In other words, I've come to believe
it's best to just do it. Do what you can, and move on to the next task/feature/enhancement
and don't worry about being perfect (worry about being good ... but, no
need for perfection). 

So, If we leave in the section at all,
I'd like a statement that it's highly discouraged, and must have PMC approval.


Protected Internal Usage

I think it should be called "protected
non-API Usage" ... "internal" is kind of ambiguous and a
fluke of Eclipse history, I think. 


Internal Use

I think you should include a link to
our Policy
on Package Visibility

= = = = =

Thanks for writing this up.