I worry that the language we use is so overloaded that it’s easy to get confused. I’ve been working with one group who is “graduating” some code and committers out of their Incubator Project. Naturally, they feel that they need to do a Graduation Review. Except that Graduation Reviews are what we use to move a project from the Incubation Phase into the Mature Phase. What they really want to do is a Move Review; they’re moving some existing code and committers from one project into another. The Incubator Project is going to remain in the Incubation Phase. No graduation involved. Does your head hurt yet?
The current version of the Eclipse Development Process (EDP) has relatively little to say about Move Reviews. Lately, I’ve been thinking that Move Reviews really are the same thing as Restructuring Reviews. With both, you really just need to specify what is changing, and why (and get your IP Log approved). Isn’t a move just a restructuring of code?
Frankly, the whole thing is more than just a little bit confusing. I find myself wondering if collapsing moves and restructures into a single thing might help. Or will it make things more complicated?
Here’s what I’m thinking:
Restructuring Review
The purpose of a Restructuring Review is to notify the community of your intent to make significant changes to one or more projects.“Significant changes” includes:
- Movement of significant chunks of functionality from one project to another;
- Modification of the project structure, e.g. combining multiple projects into a single project, or decomposing a single project into multiple projects; and/or
- Change of project scope
A Restructuring Review may include the movement of significant chunks of code. A move is considered significant if it has an impact on the community (i.e. if segments of the community will notice that the code has moved). This may include entire projects, bundles, and features, but likely excludes small (<250 LOC) fragments, code snippets and individual files. The IP Log of all moved code must be reviewed prior to the start of the review period (this, typically, is a subset of the project’s IP Log). If all of the code is moved out of a project, a Termination Review for that project can be combined with the Restructuring Review.
A Restructuring Review may necessitate the construction of one or more new projects. This tends to occur when an existing project is decomposed into two or more projects. In this case, a Restructuring Review is similar to a Creation Review. Any new projects that are created as part of a Restructuring Review must have their scope explicitly specified as part of the review. The scope of any new project must be a subset of the scope of the original project. Likewise, the set of committers assigned to a new project must be a subset of the committers of the original project (additional committers can be elected to the new project after it is created). Any new projects that fall outside of the scope of the original project, or wish to establish a different set of committers, must undergo the full project creation process.
Committers can be moved along with code into a new project as part of the project provisioning process. Committers cannot be moved along with code into an existing project. In this case, the existing project must elect the new committers into the project.
Ultimately, it is left to the discretion of the project leadership, PMC, and EMO to determine how the process can be leveraged to best serve the interests of the community.
A project should socialize pending changes using established communication channels prior to initiating the review. A Restructuring Review must provide the community with at least one week to review and respond to the changes. Prior to the start of that review period, the community must be provided with (via the EMO) completed review documentation that describes in specific terms what will be changed as part of the restructuring.
This may include:
- Name, description, scope, and committer lists of new projects that need to be created;
- Source and target locations for moves of source code directories;
- Reorganization of builds and downloads;
- Contribution questionnaires (CQs) that need to be moved or piggy-back CQs that must be created;
- Location of the approved IP Log; and
- Other information that helps the community understand the change.
When it comes down to it, the entire point of any review is to tell the community what you’re doing and give them a chance to voice their opinion.
As always, I want to hear your thoughts on the topic. This is your process. We have several bugs open; you can add your comments there. Or as comments on this blog. Or by private email (I’m the one wayne that works at eclipse.org). Whatever suits you best.
