source/chapters/pmi.adoc

[[pmi]]
== Project Management Infrastructure (PMI)

The {forgeName} Project Management Infrastructure (PMI) consolidates 
project management activities into a single consistent location and experience.

Project Management Infrastructure themes:

_Improved consistency._ Configuration/data-driven project web presence, 
direct linkage between releases, reviews, and plans. Information--including 
basic project metadata, project plans, and release review information--is 
captured and retained in a consistent (and easily leveraged) data-based 
format (rather than in multiple documents in arbitrary formats).

_All-in-one-place._ Project leads and committers are able to edit 
information in place on the project information pages. Text/information in 
one place with links in another is eliminated where possible. Comments and 
discussion related to reviews, elections, etc. are connected directly 
to the item being discussed.

_Get started faster._ By default, projects are provided with a data-driven 
website that includes consistent links to project releases, reviews, 
downloads, etc. Projects can opt to override the default and provide 
their own customized web presence. Setting up a project presence is a 
matter of configuration, not PHP programming against proprietary APIs.

[[pmi-metadata]]
=== Project Metadata

Project committers and project leads are responsible for maintaining
their project's metadata. This information is an important part of being
an Eclipse project.

Project metadata is:

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.

PMC members, and the Eclipse Foundation staff also have the ability to
make changes on behalf of a project.

[[pmi-viewing]]
=== Viewing

The complete listing of all current
{projectListUrl}[{forgeName} 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.

[[pmi-commands-and-tools]]
=== Commands and Tools

Committers have access to several committer-specific
commands and tools. The selection of commands available are context sensitive; only those
commands that make sense for the logged in user are shown.

[[pmi-editing]]
=== Editing Project Metadata

Committers have the ability to edit the information managed and displayed
on the project page.
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).

Some of the fields are described below.

[[pmi-description-and-scope]]
==== Description and Scope

The 'description' should start with a concise paragraph of three to five 
sentences (e.g. suitable for display with a collection of other projects). 
A single paragraph is generally appropriate for the
description.

If more than a single simple paragraph is required to fully
describe the project, it is possible to set a summary. The summary
can be specified by toggling the "show summary" link to explicitly
set a summary apart from the more detailed description, or the top
part of the description can be designated as the summary by inserting 
a 'Teaser Break' into the content.

NOTE: providing a summary gives you control over what will get rendered.
In views where we are displaying more than one project, 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, the Project Management Committee (PMC) must be
contacted regarding a potential restructuring review.

[[pmi-downloads]]
==== Downloads

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 left to the
project team to decide. It can be a link to a webpage, a direct link to 
a file download, or whatever else makes sense the project and community.

Optional text can be included 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. 

ifeval::["{forgeName}"=="Eclipse"]
_The Eclipse Foundation strongly encourages all projects to create an
maintain and http://marketplace.eclipse.org[Eclipse Marketplace]
presence._
endif::[]

[[source-repositories]]
==== Source Repositories

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 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 the
value is correct and try its best to display the information.

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
automatically displayed under the repository name.

NOTE: 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.

You can use wildcards to match multiple repositories, e.g.
'/gitroot/virgo/*'. Note that wildcards only work for repositories that
exist on {forgeName} infrastructure (they do not work for GitHub-based
repositories, for example). 

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.

A *Contribution Message* should be provided; it is displayed at
the top of the section and is one of the primary means by which the 
community will find the project code. 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.

[[pmi-company-logos]]
==== Company Logos

Company logos automatically appear on the _Who's Involved_ page under the following
conditions:

* 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
source code repository information specified.

[[pmi-build-technology]]
==== 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 the project team feels will help the community build
the project.

[[pmi-technology-types]]
==== 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.

Clicking on one of the technology types, will take the user
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).

[[pmi-releases]]
=== Releases and Reviews

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.

[graphviz, releases-and-reviews, svg]
.The relationship between proposals, projects, releases, and reviews.
----
digraph {
	bgcolor=transparent
	graph [ranksep="0.25", nodesep="0.25"];
	node [shape=box;style=filled;fillcolor=white;fontsize=12];

	review[label="Review"]
	proposal[label="Proposal"]
	project[label="Project"]
	release[label="Release"]

	proposal -> review[label="1:1"]
	project -> review[label="1:*"]
	release -> review[label="1:0..1"]
	proposal -> project[label="1:1"]
	project -> release[label="1:*"]

	{rank=same;proposal project release}
}
----

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

NOTE: Create a single record for each release. *Do not create release records
for milestones.* Enter milestone information in the 'Plan' information
for your release.

A project lead or committer can create a new release by clicking "Create a new release" under
"Committer Commands" on the project page. This opens a dialog requesting
that a date and name be specified. Both of these values can be changed later. 

[[pmi-release-description]]
==== Description

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.

[[pmi-release-issues]]
==== Issues

The release record will automatically generate a list of targeted bugs.

To populate this list:

* Ensure that the Bugzilla Product is set the to correct value in the
project metadata;
* Set the "target milestones" in Bugzilla need to match the name of your
release.

NOTE: The matching algorithm tries to be as forgiving as possible, a release
  named "3.5", "3.5.0", or "3.5 (Luna)" will--for example--match target
  milestones named "3.5" ,"3.5M1", "3.5 M2", "3.5.0M3", etc., but will
  not match "3.5.1".

The bugs for all projects participating in the release will be included.
Bugs are grouped by Bugzilla product and component.

[[pmi-release-plan]]
==== Plan

<<releases-plan,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).

[[pmi-release-milestones]]
==== Milestones

Enter the name, date, and optional description for each milestone
expected with the release. 

Projects should generally include more than one milestone build with each
release. To include additional milestones, click the "Add another item"
button. Note that milestones can be dragged into the desired order. To
remove a milestone, leave the "Name" field blank.

[[pmi-review]]
==== Review

The release has a <<release-review,'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.

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.

ifeval::["{forgeName}"=="Eclipse"]
[[pmi-joining-a-simultaneous-release]]
=== Joining a Simultaneous Release

Projects cannot add themselves directly to a simultaneous release (e.g.
https://projects.eclipse.org/releases/luna[Luna]), but rather must be
added by the EMO (there is a
https://bugs.eclipse.org/bugs/show_bug.cgi?id=402190[bug open] to extend
this ability to planning council members).

To join a simultaneous release:

1.  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;
2.  Send a note to the planning council (Eclipse projects normally do
this via the
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev[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 +pass:[+1]+ project's bits then your project is
probably a +pass:[+2]+ project, for example.
endif::[]