Development Resources/HOWTO/Restructuring Reviews
A Restructuring Review is an opportunity to notify the community about "significant" changes in your project. This can be as simple as a change of name or scope, or as complex as a splintering of the project into multiple projects with distinct scopes, committers, and so forth.
Any Restructuring Review that includes the movement of code from one project to another requires an IP Log review (all of the relevant CQs must be approved by the Eclipse Legal team) prior to scheduling of the review. We cannot schedule a Review before the Legal team has completed their work. If you are waiting for CQs, please review where your CQs are, and when they are scheduled to be reviewed, in the IP team work queue.
After you have verified that all relevant CQs are approved, the following items must be completed at least one week before the scheduled start of the review period:
- PMC Approval: Can occur in parallel with, prior to, and after, the IP clearance; and
- IP Log Approval (if code will be moving as part of this review)
It is good practice to provide the EMO with Review Documentation as early as possible. Due to the very dynamic nature of a Restructuring Review, some amount of negotiation may be required to get the content right (at the end of the day, the review documentation needs to serve as the means by which the community is informed of the activity). It is recommended that you provide the EMO with a draft of your documentation at least one week ahead of the start of the review period. Strictly speaking, however, completed review documentation is required prior to the start of the review period.
Please forward an email showing that you have PMC approval for the review from both the "old" and "new" PMCs (in the case that a project is moving from one Top Level Project to another). The easiest way to do this is to request approval on the PMC mailing lists and forward the responses to EMO.
Your project plan must be current, and available at this URL: http://www.eclipse.org/projects/project-plan.php?projectid=top-leve-project.sub-project. This URL must be listed in your review docuware.
IP Log Approval
Because IP Log approval can take varying amounts of time (depending on the work queue of the IP Team), Restructuring Reviews that require IP Log approval (i.e. include the movement of code from one project to another) must have an approved IP Log before their review date is confirmed. After you have submitted the IP Log to Eclipse Legal for approval, the review is added to the schedule with the notation Waiting for IP Log. After EMO is notified that the IP Log is approved, that notation is replaced with the date of the review.
Please use the automated IP Log Tool to update and and submit your IP Log. This page explains how the tool works. This section of the page explains how to submit the IP Log. The URL for using the tool for your project uses your project ID, in this format: http://www.eclipse.org/projects/ip_log.php?projectid=project ID.
While you are waiting for IP Log approval, we suggest that you obtain PMC approval for the review and begin work on your document.
Restructuring review documentation should only be as detailed as it needs to be. If the review will result in the creation of one or more new projects, you'll need to provide a description, scope, committer list, etc. for each of the new projects (consider using the project proposal template for this). If the restructuring amounts to a few bits of code being moved from one project to another, a bullet list describing how things need to be reconfigured may be enough. For a very simple restructuring, it may be enough to capture the move description in a bug comment.
For a Restructuring Review, the document describe the reasons for the move, and includes the steps you will go through to facilitate the move (aka your Move Plan). Please consider these items when writing your Move Plan:
- List the CQs from IPzilla that need to be moved to the "new" project;
- List committers who will be on the "new" project:
- If any of these were not already on the "old" project, they will need to be elected; and
- Committer bios in the review docuware serve as a mass election for these committers.
- List any committers who should be removed from the "old" project; and
- Describe the project infrastructure changes that you need to support the move, considering these areas:
- Web pages;
- Bugzilla products;
- Newsgroups; and
- Mailing lists
Please submit your document in an email attachment to EMO. Many people underestimate the time and effort needed to create the document, so be sure to allow enough time for this task. The "official" due date is the day before the start of the review period (typically a Wednesday). However, the documentation need to be reviewed by the EMO before posting. If you wait until the due date to submit the first draft and the EMO requests changes, then you'll probably miss your deadline and your review will be postponed.
Please note that that the document must be provided in a vendor-neutral file format (PDF, HTML).
Many projects overlook these items when they do their first draft:
- correct copyright notice;
- EPL notice;
- URL for the project plan (see above);
- review date;
- IP Log URL;
- Move Plan;
- Committer bios (if there are new committers); and
- Communication Channel
It is generally easier to add committers to a new project using the Developer Portal after the project has been created. However, committers can be added to a new project as part of the review if so-desired. In this event, committer bios must be provided as the review will serve in place of a committer election and new committers are required to demonstrate merit. Committer bios don't have to be long or involved, but they should describe each committer's relationship to and history with the incoming code, and/or involvement with the area or technologies covered by the proposal.
Committers can only be added to an existing project via committer election in the Developer Portal.
After a successful Restructuring Review, you will be asked to open a Bugzilla bug, assigned to Webmaster with a cc to EMO and Sharon Corbett, describing the steps that need to be done to move the project. This is basically a reiteration of the Move Plan from your review docuware.