Project Management Infrastructure/Project Metadata
What is Project Metadata?
- Relatively static structural information such as the project description and scope, the names of the project's mailing lists and newsgroups, the bugzilla products, source code repositories, etc.
- Historical information such as previous release downloads, release review slides and IP logs, etc.
- Status and future looking information such as the project and milestone plans, the features scheduled for the current release, release dates, etc.
Who maintains it?
Eclipse committers and project leads are responsible for maintaining their project's metadata. This information is an important part of being an Eclipse project.
PMC members, and the Eclipse Foundation staff also have the ability to make changes on behalf of a project.
Viewing and Editing Project Metadata
The complete listing of all current Eclipse projects provides one starting point for viewing projects. From here, you can link directly to a project information page. Navigation options are provided to help you move from one project to another.
Here is an example of a project page (visit the live project page).
If you are a project committer, you can authenticate with the system by clicking the "Login" link. Once logged in, you will have the ability to edit the information being displayed.
There are several sections on the page. When you switch the page into "Edit" mode, you will be provided with lots of help regarding the contents of each of the fields (note that the help text is currently rendered below the fields).
Description and Scope
At the top are the description and the scope. The description should be suitable for display with a collection of other projects (e.g. Use of Maven Build Technology). A single paragraph is generally appropriate for the description.
If you feel that more than a single simple paragraph is required, you can provide a single paragraph summary. Note that providing a summary gives you control over what will get rendered. In views where we are displaying more than one project (e.g. Maven), the system will artifically cut short descriptions that are too long, potentially resulting in a description that looks weird.
The scope is intended for a more select audience; generally speaking the scope should be taken directly from the project's proposal. Project members have the ability to change the text of the project scope, but should be careful to avoid changing the meaning. If the meaning of the scope needs to change, consult your PMC regarding a restructuring review.
Project Plan, and Release Links
The left-nav contains a link to the project plan. The value that is displayed here depends on the information provided. If you provide a link in the project's "Project Plan" field, that value will be used as the link. Otherwise, the PMI will create a link to a plan automatically generated from plan information provided in the chronologically next release. Note that the use of the "Project Plan" field is discouraged in favour of the plan generated from release data.
Eclipse projects can specify an XML URL in the standard format; in this case, the link will be modified to point to the project plan rendering script.
The links to the current and next release are automatically generated based on the dates of the project releases.
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.
A release record contains three categories of information.
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 #Bugs as Plan Items for more information.
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.
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 project can specify zero or more source repositories. These are displayed in the "Contribute to this Project" section.
The values specified are used to query against a database of known existing repositories. Only those repositories that actually exist are displayed.
The name that is displayed for the repository is extracted from the last segment of the URL.
If a description file exists in the Git repository, the contents are displayed under the repository name.
The script that we us to identify repositories attempts to identify a corresponding Gerrit interface for the repository. If it exists, the Gerrit URL is used in place of the Git one. If the repository uses Gerrit, then only the Gerrit URL is displayed. Otherwise, the "git://" and "ssh://" URLs are displayed.
The script also searches for GitHub and Google Source mirrors. If they exist, they are displayed in this section. The "clipboard" icon will, when clicked, copy the URL to the clipboard.
You can use wildcards to match multiple repositories, e.g. '/gitroot/virgo/*'.
Repositories are displayed in the order they are specified. The order can be changed in the edit screen by dragging entries into the desired order. All wildcard matches are sorted alphabetically by name at the end of the list.
Company logos sometimes appear under the project members on the right. Here's what you need in order to get your company's logo to show up in this pane:
- The company must be a member of the Eclipse Foundation;
- The company needs to have their logo uploaded to the Portal;
- At least one committer has to be listed as an employee of the company in question;
- The committer must be on this project; and
- The committer must be active (must have made at least one commit in the last three months)
If all of those conditions are met and the logo is still not showing up, then it’s possible that the project meta-data doesn’t have the correct version control paths specified–this affects whether the committer is considered active by the dashboard.
A project can specify a section of text, links, and a selection of the build technologies employed. Specifying this information makes it easier for members from the community to understand your build. Links can include direct links into the Hudson builds, pages of build instructions, or whatever else you feel will help the community build your project.
A project can specify the types of technology produced by the project. This is specified in rather broad terms like "OSGi" or "Runtime". The various technology types manifest as checkboxes on the edit screen. This information is used to form connections between projects to assist in navigation and discovery.
Note that by clicking on one of the technology types, you will be taken to a page that lists the projects that produce that particular type of technology, along with the summary of their description and project logo (if specified).
There is a lot more information displayed on this page. We'll fill in these details over the coming days and weeks.
Use the Generated Content for Your Project Home Page
If you want to use this page as your project home page, change the contents of your project's index.php file to:
<?php header("Location: http://projects.eclipse.org/projects/your.project.id"); ?>
(with an appropriate substitution of your.project.id, e.g. technology.egit, of course).
Note that the automatically-generated pages will continue to grow, change, and be updated.