[wtp-pmc] Clarification of "code change" process and component teams - P

[David M Williams <david_williams@xxxxxxxxxx>]

I think I've included everyone's suggestions,
and added a few clarifications that have come up. 

With the PMC's approval, 
we'll consider this our official code
change policy, 
I'll publish to a web page somewhere,
and 
announce to wtp-dev. 
and open it up for developer comment
and suggestions. 
Assuming there is PMC approval, I'll
put this in to an HTML form to publish in our website. 

I think clarifications and improvements
suggested by WTP committers can be made without 
further PMC vote as long as the gist
is maintained -- the basic structure of having 
component teams, and no impact on APIs
or adopters without careful review
and approval of component teams. 






Proposed clarification of "code change"
process.

Our WTP Charter, and the The Eclipse
general charter it refers to,
specifies the general procedure and decision process used for changing
code. 

I think WTP is far enough along and
being used for enough business critical applications, that  we, the
PMC would be best to clarify what the specific
procedures and decision processes are.


The charter itself allows the "The
PMC defines the decision process" so, my proposal is not a change
to the charter, just more 
specific. I think this is important
to be clear on this decision process before controversy arises, since WTP
is a very complex project, and 
becoming more complex, and is very heterogeneous
in the companies represented.  It is not that I anticipate controversy,

just that the current procedures and
process is a bit general. Also, I should be explicit, I have no doubt of
the good will of all
involved in WTP ... but, good will alone
is sometimes not enough when folks are committing their hard work and trying
to make long 
term business plans. 

I think my proposal is pretty much how
we have already been operating, except that I think moving forward we need
to 
do more "prep work" in side
branches, before committing to a release. 



Here is what the current (general) charter
says: 

<quote>
The Committers of a Project or component
decide which changes may be committed to the master code base of a Project
or
component respectively. The PMC defines
the decision process, but that process must include the ability for Committers
to veto the change. The decision process
employed may change with the phase of development.  Common decision
processes
include:

    * Retroactive - changes
are proactively made by Committers but can be vetoed by a single Committer.
    * Proactive - for efficiency,
some code changes from some contributors (e.g. feature additions, bug fixes)
may be
    approved in advance, or
approved in principle based on an outline of the work, in which case they
may be committed
    first and changed as needed,
with conflicts resolved by majority vote of the Committers of the Project
or component,
    as applicable.
    * Three Positive - No
code is committed without a vote; three +1 ('yes' votes) with no -1 ('no'
votes or vetoes) are
    needed to approve a code
change.

Vetoes must be followed by an explanation
for the veto within 24 hours or the veto becomes invalid. All votes are
conducted via the developer mailing
list associated with the Project or component. Special rules may be established
by
the PMC for Projects or components with
fewer than three Committers.
</quote>


Here is the specification I am proposing,
that I think covers our project in more explicit terms:  


Process of changes to the master code
base [1]:


Changes that do not require extra processes
or voting (that is, they are approved "in advance"). 

        Bug fixes,
java doc and JUnit tests can all be committed to the forward (head) stream.

        Feature
requests, if simple additions, that do not increase dependancies, or require
changes
        in APIs.
Any new features that involve API or SPI, should only be done as "
official API" -- we don't 
        want to
add to our "API debt" -- so would fall in the "new API"
category below. 

        Any evolution
of an API, as long as the API is evolved in a source and binary
        compatible
way. 

        In general,
internal changes for the sake of  better, faster, simpler and cleaner
components 
        are greatly
encouraged -- with no burdensome process required, if there's no change
to API 
        or impact
to adopters. 



Changes that do require a concrete proposal
[2], review and prior agreement [3] of component members: 

        A change
in internal non-API that is clearly identified in "usage reports"
as being used by adopters.
        Any such
proposed changes needs approval of the components committers and be open
to public review so that adopters can 
        comment,
and anticipate and minimize disruption. A typical part of such a proposal
would include what migration would involve .... a package 
        rename only,
argument changes, or a re-work of fundamental logic. Note: a "change
in non-API" in this sense includes changes in behavior
        such as
threading behavior, order of execution, etc., not just changes in signatures.


        A new API.
The main criteria here is if it meets "API Quality guidelines"
as described in the Eclipse
Development Process 
        and allows
for later API
evolution. 
        The committers
for a component (and their clients) are the primary stake holders, and
thus is their responsibility 
         to
propose and decide API and ensure its quality. But, it should be developed
in a side branch where it can be better 
         reviewed
and assessed before being committed to a build. 

        Promotion
of provisional API. While final decision is up to committers of a component
(and follows normal, "new API" guidelines 
        above,
the type of criteria here the PMC requires is that 
        1)
adopters can move from the provisional API with no churn (or, minimal,
with well documented migration steps) and 
           
    2) that by moving to the new official API, then "that
is it", it meets clients/adopters needs and there would not be 
           
    additional required migration later on. 


         Changes
to declared API. This is nearly never allowed. But, there is, judging from
history, times when it should be considered as an option, 
         either
to acknowledge some previous fundamental mistake for which no other solution
can be found. Or, more likely, sometimes an API is 
         "spec'd"
in an ambiguous way, so some change might be interpreted as a change in
behavior by some, though it might be argued that 
         it
is not, based on the intent of the spec. Etc. These sorts of cases, if
there is agreement among the component team, must be brought  forward

         to
the PMC for approval. 



 In all cases, changes to the code
should have a bugzilla associated with it, to allow good traceability for
who changed what when, and why. 
 

All the above is are processes to protect
the stability of our code base and the investment made by clients which
adopt our code. It is not intented to 
ever be an "excuse" for poor
quality, or "not being able to change" code. It is always only
a question of <b>how</b> to change or fix something, not 
whether or not some new funtion is desired
or some fix needed. 



         
      [1] Master code base means the "head"
stream, to be released for build, milestones, and the release itself. 
         
      Committers can do what they want in side branches
(within, of course, the bounds and scope of the project and Eclipse Foundation
rules). 
         
      
[2] By "concrete proposal"
is meant at least a short description of  the "problem"
and "how solved" and preferably 
the "ready-to-go-code" that
has been developed in a side branch, where it can be reviewed.  All
"new work" proposed must fit the 
scope of the charter of WTP and the
themes approved by the PMC for a given release

[3] Prior agreement means prior to committing
to head, or the release.  A simple vote in bugzilla or on developer
mailing lists
is good if its "controversial",
or if it is considered "obviously agreed to" then formal voting
record is not needed, but, 
would be subject to retroactive "veto"
if later found objectionable by a committer to a component. In the event
of disagreement
between committers, the PMC can arbitrate
a solution (which normally will strive to satisfy all requests, but, may
vary priority, schedule, 
or exactly which release a change occurs
in, or request other technical solutions be investigated). 






Component Teams

Component Teams have the responsibility
for coming up with the specific plans for their components (within the
themes established by the PMC, and the scope of our charter). 
This includes all the "normal"
duties of being a committer, providing JUnit tests, participating in test
phases, monitoring bugzilla, and participating on newsgroups and mailing
lists. 
The component team also has the right
and responsibility to vote in new committers for their component. 

The component team lead (listed first
in the lists below) has responsibility to not only lead the team, but also
to represent them in documenting formal votes for release, changes to schedules,
etc. 
where a WTP-wide vote is needed. 

There are two "components"
that have automatic membership, the website component and the releng component.

When a committer first joins WTP by
being voted in a committer to one group, there's a certain amount of "formal"
things that 
have to happen, papers signed, IDs given,
etc. If that person is then later voted into another component, it's a
much easier 
process, since the "WTP membership"
has already been established, so its just a question of the component team
member ship. 
Eventually, component team membership
could translate into CVS access, but, since that can get to be hard to
administer, we are in 
no rush to do that (since cvs is fully
traceable, we know who changed what when, so there is no risk of someone
changing something 
they shouldn't). 



People and Plugins

        Note, where
a feature is listed, its assumed to mean all the plugins in that feature,
        unless the
plugin is listed elsewhere individually.



Common (Component Team that works on
current WST and JST Common component features)


        Craig, John,
Nitin, Konstantin Komissarchik, Peter Moogk, Chuck Bridgham,    
 Kate Price, David Williams, Naci Dai

           
    org.eclipse.wst.common_core.feature
           
    org.eclipse.wst.common_sdk.feature
           
    org.eclipse.wst.common_tests.feature
           
    org.eclipse.wst.common_ui.feature
           
    org.eclipse.wst.common_userdoc.feature

           
    org.eclipse.jst.common_core.feature
           
    org.eclipse.jst.common_sdk.feature


Server (Component Team that works on
current WST and JST Server component features)

        Tim, Larry
Issacs, Gorkem Ercan, Marshall Culpepper, Rob Frost      
   Kate Price, David Williams, Naci Dai

           
    org.eclipse.wst.server_core.feature
           
    org.eclipse.wst.server_sdk.feature
           
    org.eclipse.wst.server_tests.feature
           
    org.eclipse.wst.server_ui.feature
           
    org.eclipse.wst.server_userdoc.feature

           
    org.eclipse.jst.server_adapters.feature
           
    org.eclipse.jst.server_core.feature
           
    org.eclipse.jst.server_sdk.feature
           
    org.eclipse.jst.server_tests.feature
           
    org.eclipse.jst.server_ui.feature
           
    org.eclipse.jst.server_userdoc.feature


Datatools (RDB)

        DerPing,
Shelia, Lawrence, Rupesh, Dirk         Kate Price,
David Williams

           
    org.eclipse.wst.rdb_adapters.feature
           
    org.eclipse.wst.rdb_core.feature
           
    org.eclipse.wst.rdb_sdk.feature
           
    org.eclipse.wst.rdb_tests.feature
           
    org.eclipse.wst.rdb_ui.feature
           
    org.eclipse.wst.rdb_userdoc.feature


Editors and Source code models: SSE,
XML, DTD, _javascript_ CSS, HTML, JSP, XSD


        David Williams,
Nitin, Amy, Craig, Keith,       Kate Price, Naci Dai


           
    org.eclipse.wst.xml_core.feature
           
    org.eclipse.wst.xml_sdk.feature
           
    org.eclipse.wst.xml_tests.feature
           
    org.eclipse.wst.xml_ui.feature
           
    org.eclipse.wst.xml_userdoc.feature

           
    org.eclipse.wst.css.core
           
    org.eclipse.wst.html.core
           
    org.eclipse.wst._javascript_.core
           
    org.eclipse.wst.css.ui
           
    org.eclipse.wst.html.ui
           
    org.eclipse.wst._javascript_.ui

           
    org.eclipse.jst.jsp.core
           
    org.eclipse.jst.jsp.ui


Web Services and WSDL (Component Team
that works on current WST and JST Server component features)

        Chris, Kathy,
Peter, Craig, Richard, David L,   Kate Price, David Williams, Naci
Dai

           
    org.eclipse.wst.ws_core.feature
           
    org.eclipse.wst.ws_sdk.feature
           
    org.eclipse.wst.ws_tests.feature
           
    org.eclipse.wst.ws_ui.feature
           
    org.eclipse.wst.ws_userdoc.feature


Web Projects (Component Team that works
on current WST and JST Project models, refactoring, etc)


        Chuck, John,
Rob Frost                  
               Naci Dai, Kate Price,
David Williams

           
    org.eclipse.jst.web_core.feature
           
    org.eclipse.jst.web_sdk.feature
           
    org.eclipse.jst.web_tests.feature
           
    org.eclipse.jst.web_ui.feature
           
    org.eclipse.jst.web_userdoc.feature

           
    org.eclipse.wst.web_core.feature
           
    org.eclipse.wst.web_sdk.feature
           
    org.eclipse.wst.web_tests.feature
           
    org.eclipse.wst.web_ui.feature
           
    org.eclipse.wst.web_userdoc.feature


JEE and EJB2 (Component Team that works
on current JST J2EE and EJB)

        Chuck, John,
Sinan Konya, Naci Dai, Rob Frost          Kate
Price, David Williams

           
    org.eclipse.jst.enterprise_core.feature
           
    org.eclipse.jst.enterprise_sdk.feature
           
    org.eclipse.jst.enterprise_tests.feature
           
    org.eclipse.jst.enterprise_ui.feature
           
    org.eclipse.jst.enterprise_userdoc.feature





Background

"Component" is used in many
ways, so for the purposes here,  "Component Team", means
those committers responsible for one or more 
components of code (and the corresponding
components of bugzilla, cvs, etc). 

Here's a "picture" of the
organization we will have during WTP 2.0 development (numbers are approximate),

I think WST and JST are "too big"
for efficient, agile development by Component Teams.

Webtools (WST and JST) 23

        IBM      14
        BEA       3
        Turkcell  1
        Eteration 2
        JBoss     1
        SAS       1
        Oracle    1

Dali:            11

        Oracle:   6
        Versant:  3
        BEA       1
        JBoss     1
       
       
JSF:              5

        Oracle:   4
        Sybase    1


ATF:              5

        IBM:      5

I think we should be explicit, that Dali (JPA), JSF, and ATF, will remain being their own component teams, for
decision making, planning, etc. as well as them "voting in" their own future committers that they would find valuable. That is,
if/when they graduate incubation, and if/when joint WTP, they would join as their own WTP Component Team, in the sense of this document.