Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Project Management Infrastructure/Project Metadata"

(→‎Downloads)
(41 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== What is Project Meta-Data?==
+
== What is Project Metadata?==
−
# Relatively static structural information such as the names of the project's mailing lists and newsgroups, the bugzilla products and CVS repository, etc.
+
# 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.
 
# 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.
 
# 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?===
 
=== Who maintains it?===
−
Eclipse committers and project leads are responsible for maintaining their project's meta-data. This information is an important part of being an Eclipse project.
+
Eclipse committers and project leads are responsible for maintaining their project's metadata. This information is an important part of being an Eclipse project.  
  
−
=== How do I maintain my meta-data?===
+
PMC members, and the Eclipse Foundation staff also have the ability to make changes on behalf of a project.
−
Use the [http://portal.eclipse.org/ portal].  Look in Eclipse Projects > [view] > [maintain] Project meta-data.
+
  
−
==What Meta-Data Do you Need to Provide?==
+
==Viewing and Editing Project Metadata==
  
−
In this section, we describe the many fields that you'll find in the portal.  
+
The complete listing of all current [http://projects.eclipse.org/list-of-projects 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.
  
−
===Basic Information===
+
Here is an example of a project page (visit the [http://projects.eclipse.org/projects/technology.egit live project page]).
  
−
You should minimally provide the following information for your project.
+
[[Image:PMI-project-page.png|400px|center|The Project Page displays project metadata]]
  
−
{| cellpadding="10" cellspacing="0" border="1"
+
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.
−
!Name        !! Field !! Description
+
−
|-
+
−
|Paragraph || paragraphurl || This is a single URL for an HTML file in your project's web directory that contains a concise (e.g., 50-100 word) description of your project. The content of this file is intended to be aggregated with other project paragraphs in lists (e.g., release train projects, top-level project summary lists, ...). Keep the content as simple as possible (i.e. avoid left- or right-aligned images, div tags, etc.). The goal is to motivate readers to identify your project as interesting, not convey deep technical content. You may specify the URL as absolute (e.g. <nowiki>http://www.eclipse.org/woolsey/description.html</nowiki>) or relative to the web root (e.g. /woolsey/description.html). Note that however you choose to specify this value, the resulting URL must be relative to <nowiki>http://www.eclipse.org/</nowiki>.
+
−
|-
+
−
|Description || descriptionurl || This is a single URL for an HTML file in your project's web directory that contains a short (e.g. 2-3 paragraph) description of your project. The content of this file is used, for example, in on the project summary page for your project. Keep the content as simple as possible (i.e. avoid left- or right-aligned images, div tags, etc.). The goal is to motivate readers to identify your project as interesting, not convey deep technical content. You may specify the URL as absolute (e.g. <nowiki>http://www.eclipse.org/woolsey/description.html</nowiki>) or relative to the web root (e.g. /woolsey/description.html). Note that however you choose to specify this value, the resulting URL must be relative to <nowiki>http://www.eclipse.org/</nowiki>.
+
−
|-
+
−
|Short name || projectshortname || This is the short name (aka nickname) for your project. For example, the projectname for ECF might be Eclipse Communications Framework whereas the shortname would be ECF.
+
−
|-
+
−
|Homepage    || projecturl || This is a single URL that points to your project's main page. The link can be to any eclipse.org property. Links can be absolute (e.g. <nowiki>http://www.eclipse.org/woolsey</nowiki>, <nowiki>http://eclipse.org/woolsey</nowiki>, or <nowiki>http://wiki.eclipse.org/Woolsey</nowiki>) or relative (e.g. <nowiki>/woolsey</nowiki>). Relative links are assumed to be relative to <nowiki>http://www.eclipse.org</nowiki>.
+
−
|-
+
−
|Download    || downloadsurl || This is a single URL that points to the project's downloads. The link can be to any eclipse.org property. Relative links are assumed to be relative to <nowiki>http://www.eclipse.org</nowiki>.
+
−
|}
+
  
−
===Community Contact Information===
+
[[Image:PMI-edit.png|center]]
  
−
Be sure to provide information about your project's newsgroups, mailing lists, and more so that your community will know where to find you.
+
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).
  
−
{| cellpadding="10" cellspacing="0" border="1"
+
===Description and Scope===
−
!Name        !! Field !! Description
+
At the top are the description and the scope. The description should  be suitable for display with a collection of other projects (e.g. [http://projects.eclipse.org/build-technology/maven Use of Maven Build Technology]). A single paragraph is generally appropriate for the description.
−
|-
+
−
|Newsgroups  || newsgroup || You can specify multiple newsgroups. This information is used to inform your community of the newsgroups and forums available for your project (the same information is used to render links to both newsgroups and forums). For each newsgroup/forum, you specify the name, optional description, and type. The name is as it appears on the news server (e.g. eclipse.woolsey). A short description will help visitors decide which newsgroup or forum to visit and so it is highly recommended that you provide a value here. Generally a project will have a single "main" newsgroup/forum. This information is used when rendering newsgroups (in cases where there is only room to list one, the main newsgroup/forum is listed).
+
−
|-
+
−
|Mailing Lists || mailinglist || You can specify multiple mailing lists. This information is used to inform your community of the mailing lists available for your project. For each mailing list, you specify the name, optional description, and type. The name is specified without the domain (e.g. woolsey-dev). A short description will help visitors decide which mailing list to use and so it is highly recommended that you provide a value here. Generally a project will have a single "main" mailing list. This information is used when rendering mailing lists (in cases where there is only room to list one, the main mailing list is listed).
+
−
|-
+
−
|Wiki        || wikiurl || This is a link to the project's landing page in the wiki. You may specify the URL as absolute (e.g. <nowiki>http://wiki.eclipse.org/Woolsey</nowiki>) or relative to the wiki root (e.g. /Woolsey). Note that however you choose to specify this value, the resulting URL must be relative to <nowiki>http://wiki.eclipse.org/</nowiki>.
+
−
|-
+
−
|Docs        || documentationurl ||  This is a single URL that points to the project's documentation. Typically this is a link into <nowiki>http://help.eclipse.org</wiki> (e.g. <nowiki>http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.egit.doc/help/EGit/User_Guide/User-Guide.html</nowiki>, but the link can be to any eclipse.org property. Relative links are assumed to be relative to <nowiki>http://www.eclipse.org</nowiki>.
+
−
|}
+
  
−
===More===
+
[[Image:PMI-DescriptionSummary.png|center|500px|frame|Editing the scope. Toggle the summary with "Hide/Show Summary"]]
−
{| cellpadding="10" cellspacing="0" border="1"
+
−
!Name        !! Field !! Description
+
−
|-
+
−
|Logo || logourl || A single URL that points to a file containing the logo for your project.
+
−
|-
+
−
|Source Repository || sourcerepository || Multiple entries can be provided for the source repository. As the name suggests, this field lists the locations of the repositories that hold the source for your project. This information is used to inform your community of the location of these resources, but also to feed the Dash tools concerned with gathering commit statistics. CVS locations are e.g. /cvsroot/technology/org.eclipse.buckminster. SVN locations are e.g. /technology/org.eclipse.buckminster. Git repositories are specified using any valid Git URL (Git URLs must be relative to git.eclipse.org).
+
−
|-
+
−
|Update site || updatesiteurl || This value is a single URL that points to your project's main update site. The URL must be relative to <nowiki>http://download.eclipse.org/</nowiki>.
+
−
|-
+
−
|Releases || release || Projects are required to make an entry for each release. Valid release status includes: scheduled, completed, tentative.
+
−
|-
+
−
|Bugs || bugzilla || Specify a Product Name, Component Name and URL for your project's bugs.
+
−
|-
+
−
|Articles || articleurl || Specify multiple URLs to articles and other interesting links that reference your project. URLs are not restricted (i.e. you can link to articles posted outside of <nowiki>eclipse.org</nowiki>). Relative URLs are assumed to be relative to <nowiki>http://eclipse.org/</nowiki>
+
−
|-
+
−
|Project Plan || projectplanurl || This is a single URL that points to an XML file containing your project plan in the [[Development Resources/Project Plan | standard format]].
+
−
|}
+
  
−
===Inheritence===
+
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. [https://projects.eclipse.org/build-technology/maven Maven]), the system will artifically cut short descriptions that are too long, potentially resulting in a description that looks ''weird''.
−
Currently sub-projects/components can inherit from their parent project by setting the "Inherit" key in the meta-data editor. This special key will cause web pages and other places where the meta-data is used, to override all values other than the projectname key. This is typically used for very small projects or components which do not need to maintain much information.
+
  
−
==Where is Project Metadata used?==
+
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.
  
−
===/projects/ page===
+
===Downloads===
−
<table border="1">
+
−
<tr><th>What</th><th>Data Storage w/ Link to How to Update</th></tr>
+
−
<tr>
+
−
<td>Project Name</td><td> <b>projectname</b> in the project meta data. Use the  [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Info Page</td><td>Standard format page for all projects</td></tr>
+
−
<tr><td>Phase</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@]
+
−
</td></tr>
+
−
<tr><td>Home Page</td><td> <b>projecturl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Newsgroup</td><td> <b>newsgroup.name</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Mailing List</td><td> <b>mailinglist.name</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Wiki</td><td> <b>wikiurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
  
−
<tr><td>IP Log</td><td> <b>iplogurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
[[Image:PMI-downloads-edit.png|thumb|The Downloads section in project metadata]]
−
</td></tr>
+
−
</table>
+
  
−
===Standard project information page===
+
You can provide download information for your project in the "Downloads" section.
−
E.g., [http://www.eclipse.org/projects/project_summary.php?projectid=technology.dash Project Dash's standard information page]
+
  
−
For those more visual people, there's also an [http://wiki.eclipse.org/Image:Standard-project-page-annotated.gif annotated screenshot] of a standard information page.
+
The first entry is the main "Downloads URL". This manifests as a "Big Button" Download on the project page. What you put here is up to you. It can be a link to a webpage, a direct link to a file download, or whatever else makes sense to you and your project's community.
−
<table border="1">
+
−
<tr>
+
−
    <td>Name</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@]
+
−
</td></tr>
+
−
<tr><td>Download</td><td> <b>downloadsurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Description</td><td> <b>descriptionurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
This is a single URL for an HTML file in your project's web directory that contains a description of the project, its goals and
+
−
perhaps its status. If the url points to an eclipse.org website page, we attempt to extract the midcolumn contents as the paragraph.</td></tr>
+
−
<tr><td>Logo</td><td> <b>logourl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Commits Activity</td><td> <b>sourcerepository</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Newsgroups</td><td> <b>newsgroup.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
  
−
<tr><td>Mailing Lists</td><td> <b>mailinglist.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
You can optionally provide some text to include along with the "Big Button" Download, as well as links to zero or more Eclipse Marketplace, update/p2 sites, or other downloads. Each of the links can have an optional title (the link itself will be displayed if no title is provided). Note that no validation is done on the links to ensure that they are meaningful. It is up to use to employ the principle of least surprise for your community and adopters.
−
</td></tr>
+
−
<tr><td>Source Repository</td><td> <b>sourcerepository.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Committers</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@].  
+
−
Activity is taken from the [http://dash.eclipse.org/dash/commits/web-app/ commits explorer]
+
−
driven by <b>sourcerepository</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
<em>Active</em> is any commit activity in the last three months, <em>participating</em> is any
+
−
in the last nine months.
+
−
Company logos are shows for [http://www.eclipse.org/membership/ member companies]
+
−
of active committers.</td></tr>
+
  
−
<tr><td>Leaders</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@]
+
Here is an example of a project that has specified a download URL ("Big Button" download) and a single Marketplace Entry:
−
</td></tr>
+
−
<tr><td>Update site</td><td> <b>updatesiteurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Releases</td><td> <b>release.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
Valid release status includes: scheduled, completed, tentative.</td></tr>
+
  
−
<tr><td>Bugs</td><td> <b>bugzilla</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
[[Image:PMI-downloads.png]]
−
</td></tr>
+
 
−
<tr><td>Website</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@]
+
 
−
</td></tr>
+
''The Eclipse Foundation strongly encourages all projects to create an maintain and [http://marketplace.eclipse.org Eclipse Marketplace] presence.''
−
<tr><td>Wiki</td><td> <b>wikiurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
 
−
</td></tr>
+
===Project Plan, and Release Links===
 +
 
 +
The navigation area 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.
 +
 
 +
===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).
 +
 
 +
[[Image:PMI-Releases.png|center]]
 +
 
 +
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 [[Project Management Infrastructure/Release Metadata|Release Metadata]].
 +
 
 +
===Source Repositories===
 +
 
 +
The project can specify zero or more '''source repositories'''. These are displayed in the "Contribute to this Project" section.
 +
 
 +
[[Image:PMI-contribute.png|center|500px|frame|The Contribute section on a project page]]
 +
 
 +
The values specified are used to query against a database of known existing source repositories (this database is updated nightly by a discovery process). Those repositories that are found in the database will be displayed with enhanced information (including links to repository mirrors, Gerrit, etc.). All values that you provide will be displayed, whether they point to real repositories or not. If the database does not contain your repository, the PMI will assume that you know what you're doing and try its best to display the information. Note that it is assumed that any repository you list exists on the forge.
 +
 
 +
Repositories should be specified using the file system path, e.g. '/gitroot/egit/egit.git'. 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/*'. Note that wildcards only work for repositories that are represented in our database. If you use a wildcard entry, matching entries may not appear until the discovery process runs.
 +
 
 +
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.
 +
 
 +
You can optionally provide a '''Contribution Message''' that is displayed at the top of the section. Arbitrary text is permitted, but we recommend that you limit this content to a single paragraph with a few sentences that include a link to more information. For more information regarding what you should include here (or in a more comprehensive contribution guide), please see {{Bug|397644}}.
 +
 
 +
===Company Logos===
 +
{{Warning|This isn't currently implemented. See {{Bug|403494}}.}}
 +
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 [http://eclipse.org/membership/ 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.
 +
 
 +
===Build Technology===
 +
 
 +
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.
 +
 
 +
===Technology Types===
 +
 
 +
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).
 +
 
 +
===More===
  
−
<tr><td>Documentation</td><td> <b>documentationurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
There is a lot more information displayed on this page. We'll fill in these details over the coming days and weeks.
−
</td></tr>
+
−
<tr><td>Articles</td><td> <b>articleurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Project Plan</td><td> <b>projectplanurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Mentors</td><td> Set by Architecture Council members using the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
</table>
+
  
−
===Project Plan Page===
+
==Use the Generated Content for Your Project Home Page==
−
<table border="1">
+
−
<tr><td>Project Plan</td><td> <b>projectplanurl</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
        Also see the [[Development_Resources/Project_Plan|documentation]].</td></tr>
+
−
</table>
+
  
−
===Mailing Lists Page===
+
If you want to use this page as your project home page, change the contents of your project's ''index.php'' file to:
−
The eclipse.org [http://www.eclipse.org/mail list of mailing lists].
+
−
<table border="1">
+
−
<tr> <td>Mailing List</td><td> <b>mailinglist.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Topics</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@]
+
−
</td></tr>
+
−
</table>
+
  
−
===Newsgroups Page===
+
<?php
−
The eclipse.org [http://www.eclipse.org/newsgroups/ list of newsgroups].
+
header("Location: http://projects.eclipse.org/projects/your.project.id");
−
<table border="1">
+
?>
−
<tr> <td>Newsgroup</td><td> <b>newsgroup.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
</td></tr>
+
−
<tr><td>Topics</td><td> Foundation internal database. Email [mailto:emo@eclipse.org emo@]
+
−
</td></tr>
+
−
</table>
+
  
−
===Timeline===
+
(with an appropriate substitution of ''your.project.id'', e.g. technology.egit, of course).
−
The eclipse.org [http://www.eclipse.org/projects/timeline/ timeline page].
+
−
<table border="1">
+
−
<tr>
+
−
<td>Releases</td><td> <b>release.*</b> in the project meta data. Use the [http://portal.eclipse.org/ portal].
+
−
Valid release status includes: scheduled, completed, tentative.</td></tr>
+
−
</table>
+
  
 +
Note that the automatically-generated pages will continue to grow, change, and be updated.
  
−
== When is project status information considered out-of-date?==
+
==Where is Project Metadata Used==
−
Different kinds of information go out of date at different rates and        times, but here's an easy checklist:
+
−
* All structural status information is out-of-date if it does not            match the infrastructure. For example, if the project has added a            new project-announce@ mailing list, but the project status files do            not list that mailing list, then they are out of date.
+
−
* Status summaries must be updated at least once a quarter. It's            better to update them once a month.
+
−
* Historical information (downloads, release information, and so on)            and status summaries need updating with each release (obviously).
+
  
−
== Why is project status information important?==
+
Project metadata is used in a few different places today, and usage will continue to expand. Below are a few examples.
−
Eclipse projects belong to a larger community - Eclipse - which is comprised of not only the committers and developers on the project, but also the developers on other projects, plug-in developers outside the Eclipse projects, and the entire ecosystem surrounding Eclipse. In order to keep all these people up-to-date on the direction and status of the Eclipse projects, each project
+
−
needs to provide timely and accurate descriptive and status information. (See "[http://www.eclipse.org/projects/dev_process/development_process.php#2_4_Eclipse_Ecosystem 2.4 Eclipse Ecosystem]" in the Eclipse Development Process.)
+
  
−
The project status information drives a number of the        eclipse.org web pages including [http://www.eclipse.org/ the categories on the home page], [http://www.eclipse.org/projects/dashboard/ the dashboard],        [http://www.eclipse.org/projects/timeline/ the timeline],        [http://www.eclipse.org/projects/ lists of projects],        lists of [http://www.eclipse.org/mail/ mailing lists] and [http://www.eclipse.org/newsgroups/ newsgroups],       status pages, and more.
+
* Projects using  [http://projects.eclipse.org/build-technology/tycho Tycho], or [https://projects.eclipse.org/build-technology/maven Maven]. The description and project logo are used here.
 +
* Projects participating in the [https://projects.eclipse.org/releases/kepler Kepler simultaneous release]. We'll add a page that includes descriptions, logos, links to the project plan, and maybe contact information.
  
−
== Using the Infrastructure==
+
The project description is used in a lot of different places. Keep your project description concise; it is a means by which you can encourage people to take a closer look at your project; do not try to describe every little nuance of your project in the description. Note that you can separate out a summary of your description that will be used in lieu of the longer form which will be displayed on the project page.
−
<span style="margin-right:6px; margin-top:5px; float:left; color:ivory; background:#FF9999; border:1px solid #444; font-size:30px; line-height:25px; padding-top:2px; padding-left:2px; padding-right:2px; font-family:times; ">R</span>All projects are [http://www.eclipse.org/org/documents/Eclipse_Project_Requirements.html required] to use the standard left menu on the project home page. See the [http://www.eclipse.org/projects/dev_process/project-status-infrastructure/left-menu.php detailed, but easy, instructions] for how to make that left menu appear.
+
  
 +
[[Category:Project Management Infrastructure]]
 
[[Category:Development_Resources]]
 
[[Category:Development_Resources]]
 
[[Category:How to Contribute]]
 
[[Category:How to Contribute]]
 +
[[Category:Project Metadata]]

Revision as of 13:19, 31 May 2013

What is Project Metadata?

  1. 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.
  2. Historical information such as previous release downloads, release review slides and IP logs, etc.
  3. 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).

The Project Page displays project metadata

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.

PMI-edit.png

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.

Editing the scope. Toggle the summary with "Hide/Show Summary"

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.

Downloads

The Downloads section in project metadata

You can provide download information for your project in the "Downloads" section.

The first entry is the main "Downloads URL". This manifests as a "Big Button" Download on the project page. What you put here is up to you. It can be a link to a webpage, a direct link to a file download, or whatever else makes sense to you and your project's community.

You can optionally provide some text to include along with the "Big Button" Download, as well as links to zero or more Eclipse Marketplace, update/p2 sites, or other downloads. Each of the links can have an optional title (the link itself will be displayed if no title is provided). Note that no validation is done on the links to ensure that they are meaningful. It is up to use to employ the principle of least surprise for your community and adopters.

Here is an example of a project that has specified a download URL ("Big Button" download) and a single Marketplace Entry:

PMI-downloads.png


The Eclipse Foundation strongly encourages all projects to create an maintain and Eclipse Marketplace presence.

Project Plan, and Release Links

The navigation area 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.

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

PMI-Releases.png

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.

Source Repositories

The project can specify zero or more source repositories. These are displayed in the "Contribute to this Project" section.

The Contribute section on a project page

The values specified are used to query against a database of known existing source repositories (this database is updated nightly by a discovery process). Those repositories that are found in the database will be displayed with enhanced information (including links to repository mirrors, Gerrit, etc.). All values that you provide will be displayed, whether they point to real repositories or not. If the database does not contain your repository, the PMI will assume that you know what you're doing and try its best to display the information. Note that it is assumed that any repository you list exists on the forge.

Repositories should be specified using the file system path, e.g. '/gitroot/egit/egit.git'. 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/*'. Note that wildcards only work for repositories that are represented in our database. If you use a wildcard entry, matching entries may not appear until the discovery process runs.

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.

You can optionally provide a Contribution Message that is displayed at the top of the section. Arbitrary text is permitted, but we recommend that you limit this content to a single paragraph with a few sentences that include a link to more information. For more information regarding what you should include here (or in a more comprehensive contribution guide), please see bug 397644.

Company Logos

Warning2.png
This isn't currently implemented. See bug 403494.

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.

Build Technology

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.

Technology Types

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

More

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.

Where is Project Metadata Used

Project metadata is used in a few different places today, and usage will continue to expand. Below are a few examples.

  • Projects using Tycho, or Maven. The description and project logo are used here.
  • Projects participating in the Kepler simultaneous release. We'll add a page that includes descriptions, logos, links to the project plan, and maybe contact information.

The project description is used in a lot of different places. Keep your project description concise; it is a means by which you can encourage people to take a closer look at your project; do not try to describe every little nuance of your project in the description. Note that you can separate out a summary of your description that will be used in lieu of the longer form which will be displayed on the project page.

Retrieved from "https://wiki.eclipse.org/index.php?title=Project_Management_Infrastructure/Project_Metadata&oldid=338511"

Copyright © Eclipse Foundation, Inc. All Rights Reserved.