Project Management Infrastructure/Release Metadata
Projects, Releases, and Reviews are presented as separate records. Each project record, obviously, represents information about a project. A project may have multiple releases; information about the release is represented in a release record. The release record also contains some review information. This information is included here, because all releases do not necessarily have a review (a project can opt to provide some "review" type information as part of a release record. A project can have multiple review records; as release reviews are the most common form of review, most review records will be joined to a release record.
A review record, however, does not require a release association. Some reviews are associated with proposals. Other have no other association (e.g. termination reviews).
Each release has its own record in the database. Records are connected directly to a single specific project; a subset of release records associated with a project are displayed on the project page. An existing release can be edited in much the same was as a project. Any logged in project member (committer or project lead) can click the "Edit" button.
Add a new release by visiting the project's "Releases" page--either by clicking on "Releases" in the navigation block, or by clicking "Explore all <count> releases"--and entering information into the form (the form only appears for authored users).
Specify a date and name. Both of these values can be changed later. If you click "Create", you will be returned to the "Releases" page (where you can create another release). If you click "Create and edit", you'll be taken to a page where you can specify additional information about the release.
Please see Release Metadata.
Describe the release in the "Description" section. The description should generally be a concise paragraph describing the focus of the release (e.g. adding certain functionality, fixing bugs, etc.) in a form that is appropriate in an aggregation (e.g. a page that displays the release information for all projects participating in an instance of the Simultaneous release). The description should provide enough information to encourage the reader to click the "find out more" link.
Project plan information belongs in the "Plan" section. This information should generally be provided early in the development cycle to allow the various communities the ability to understand and participate in the release. It is expected that the plan will evolve over time. Note that all projects are required to provide a plan for each major and minor release (plans are not required service releases). Note that you can provide multiple "themes" for a release and each theme may contain a Bugzilla URL that will be used to populate lists of bugs targeted by the theme in the release (see below).
You can render the plan as a page by tacking '/plan' after the URL for the release.
- Hudson 3.1 release: http://projects.eclipse.org/projects/technology.hudson/releases/3.1.0
- Hudson 3.1 plan: http://projects.eclipse.org/projects/technology.hudson/releases/3.1.0/plan
A link to the plan for the chronologically-next release is automatically generated and displayed in the project information block (which appears in the left navigation area on projects.eclipse.org). If the "Plan URL" is set in the project metadata, its value will override the automatically-generated one.
Bugs as Plan Items
The Bugzilla URL must be a "search" URL with the following form:
The goal of the bugzilla queries is to support the use of bugzilla items for planning. The project team should assign target milestones to each bug, including both defects and enhancements. Additionally, the team should assign keywords (or keywords-in-titles) to each bug entry in order to classify them into themes. The bugzilla queries would then be, e.g., "all 2.6M1, 2.6M2, 2.6M3, ..., 2.6 bugs with keyword 'designforextensibility'", etc.
One option for mapping to the committed / proposed / deferred items is that all bugs with explicit milestones assigned are considered committed; those assigned a generic milestone or "---" are considered proposed; those assigned a milestone like "Future" are considered deferred. Another idea is to only retrieve bugs with a "plan" or "investigate" keyword by the queries, or to only add bugs with specific priorities, in order to avoid flooding the plan with less interesting small items.
If a project chooses not to use bugzilla item for planning (contrary to collective wisdom of the senior Eclipse project leads), the project plan format allows arbitrary html text paragraph(s) instead.
The release has a "Review" section that can be used to provide information for the associated review. If you provide information here, the release record itself can be used as review documentation; no further documentation is required.
Each section on the review page includes a little help to describe the sort of information that you should provide.
There is more help, including a handy Release Review checklist, on the Release Reviews page.
All major and minor releases require a review. Service releases (i.e. bug fix releases that do not change public APIs or add new functionality) do not require a review.
If a release requires a review, you can schedule one by clicking the "Schedule a review" button.
The drop-down list above the button contains several options for review dates. Pick the one that works best for you.
Note that this form will not appear if a review has already been scheduled, or the release date does not provide enough time to run a review (or is in the past). If a review has been scheduled, a link to the review will appear.
You can edit the review document, but there's really not all that much to edit. A free-form text field is available and can be used if there is some need to provide review-specific information that might not otherwise be an appropriate part of the release record. This field is intended for other types of review (e.g. restructuring or termination reviews); we decided to leave it available for release reviews for cases in which it might be useful rather than suppress it.
When the review is displayed, it automatically includes the "review" information from the release record; it shows the review-specific information at the top of the page, and includes the "review" information from the release as the rest of the page contents.
This can make things a bit confusing when you want to make changes to the metadata for a review record. Just remember that the "review" information for a release is stored in the release record.
The content in the red-dashed box comes from the review record; everything else (below the box) comes from the release record. You can get access to the release record by clicking the release name ("1.2.0" in this example).
Joining a Simultaneous Release
To join a simultaneous release:
- Create a release record:
- Provide at least a description of the release initially;
- The date of the release should generally match that of the simultaneous release;
- Send a note to the planning council (Eclipse projects normally do this via the cross-project-issues-dev mailing list) with the name of your project, the name/number of the release, and the offset.
The offset indicates how many days after the start of the aggregation process for a milestone your project's bits will be available. If your project's bits depend on a "+1" project's bits then your project is probably a "+2" project, for example.