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.

Overview

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:

1. Assemble review documentation;
2. PMC Approval(s); and
3. 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.

PMC Approval(s)

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.

Project Plan

Your project plan must be current. Include the URL for your current plan in your review documentation.

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.

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.

Creating New Projects During Restructuring

A creation review can be included with a restructuring review in the event that a project's scope needs to be split. A project that provides runtime and tools for a particular technology might, for example, be split into a project that provides the runtime and another that provides tools.

As with "normal" project creation reviews, the EMO(ED) must approve the scope of all newly-changed projects and new project names must be approved as trademarks by the legal team (trademark searches will be initiated by the EMO).

It is generally inappropriate to create a new project when using a restructuring review to move code out of a permanent incubator:

• Permanent incubator projects tend to have a broad scope that does not generally change as part of this sort of restructuring; and
• A community review is not required to create a permanent incubator.

If you want to move code out of a permanent incubator into a new project, you should instead create a project proposal citing the incubator's code as the initial contribution to the new project. For more information, please see Starting a new Open Source Project.

Your PMC and the EMO can help you determine the best way to proceed.

Review Documentation

Restructuring review documentation is captured in the Project Management Infrastructure (PMI). The EMO can create a restructuring review document in the PMI on your behalf (send an email to make this request).

Restructuring review documentation should only be as detailed as it needs to be.

If the restructuring amounts to a few bits of code (or complete Git repositories) being moved from one project to another, a bullet list describing how things need to be reconfigured may be enough.

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;
• List any committers who should be removed from the "old" project;
• Describe the project infrastructure changes that you need to support the move, considering these areas:
  • Source code repositories;
  • Web pages;
  • Bugzilla products;
  • Newsgroups; and
  • Mailing lists

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.

• URL for the project plan (see above);
• review date;
• IP Log URL;
• Move Plan; and
• Communication Channel

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 documentation.