source/chapters/pmi.adoc

////
 * Copyright (C) 2015 Eclipse Foundation, Inc. and others. 
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-License-Identifier: EPL-2.0
////

[[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 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 forums, the bugzilla products, source code repositories, etc.
2.  Historical information such as previous release downloads, 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 <<pmi-project-page,project page>>. Navigation options are provided to help you move from one project to another.

[[pmi-project-page]]
=== Project Pages

The PMI provides a website for every project based on the <<pmi-metadata,project metadata>>. This website includes an _Overview_ page that shows basic information about the project, a _Downloads_ page that provides links to downloads, a _Developer Resources_ page that includes links to <<source-repositories,source code repositories>>, and more. 

An example project page is shown below. The _Overview_ page includes the name and description of the project, list of project licenses, a table of recent releases, and various charts and other information (note that more charts are displayed on the _Who's Involved_ page. The website also includes links to project-specific <<pmi-commands-and-tools,commands and tools>> when the user is logged in as a project committer.

.A logged in committer can access commands and tools from the _Committer Tools_ block on the right side of the project page.

image::images/project-page.png[]

The URL for a project page takes the form `pass:c,a[{forgeUrl}/projects/<projectid>]` (e.g. `pass:c,a[{forgeUrl}/projects/technology.foo]`), where `pass:c,a[<projectid>]` is the qualified <<resources-identifers,identifier>> for the project.

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

Committers have access to several committer-specific commands and tools in the _Committer Tools_ block on the right side of project pages. The selection of commands available are context sensitive; only those commands that make sense for the logged in user are shown.

[[pmi-commands-cq]]
==== Create a Contribution Questionnaire

Any project committer create <<ip-cq, Contribution Questionnaire>> (CQ). CQs are required to track the due diligence review of contributions of project content and third-party content

To create a Contribution Questionnaire:

1. Log in to the {forgeUrl}[PMI];
2. Navigate to a <<pmi-project-page,project page>>;
3. Click menu:Committer Tools[Intellectual Property > Create a Contribution Questionnaire]; and
4. Follow the workflow.

[NOTE]
====
The CQ creation process works in two parts. First you create the CQ, then (when required) you attach the source code. You can attach the source code immediately after creating the CQ (otherwise the system will email you with instructions).
====

[[pmi-commands-iplog]]
==== Submit a Project's IP Log for Review

Any project committer generate the <<ip-iplog, Intellectual Property (IP) Log>> and submit it for review by the Eclipse IP Team. An IP Log review is required, for example, for all <<release-review, release and progress reviews>>.

To generate an IP Log:

1. Log in to the {forgeUrl}[PMI];
2. Navigate to a <<pmi-project-page,project page>>;
3. Click menu:Committer Tools[Intellectual Property > Generate IP Log]; and
4. Follow the workflow.

[[pmi-commands-release]]
==== Create a New Release

A project lead or committer can create a new <<release,release>> record. This opens a dialog requesting that a date and name be specified. Both of these values can be changed later.

To generate an IP Log:

1. Log in to the {forgeUrl}[PMI];
2. Navigate to a <<pmi-project-page,project page>>;
3. Click menu:Committer Tools[Releases > Create a new release]; and
4. Follow the workflow.

[[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 menu: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 (especially those that produce Eclipse Platform Plug-ins and Features) 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 {memberUrl}[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_. Th 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, images/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 switch to the _Edit_ tab.

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

[TIP]
====
Use the <<pmi-commands-release, Create a new release>> command on a specific <<pmi-project-page, project page>> in the <<pmi,Project Management Interface (PMI)>> to create a new release record.
==== 

[[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 menu: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 <<release-milestones,milestone>> expected with the release. 

Projects should generally include more than one milestone build with each release. To include additional milestones, click the btn:[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 record has a <<release-review,_Review_>> section that can be used to provide information for the associated review. If you provide information in the _Review_ section, 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.

[NOTE]
====
A review is not necessarily required for every release. A project team may declare official major or minor releases and distribute associated products for up to one year following a successful _<<release-review,release or progress review>>_ and reviews are never required for bug-fix/service releases. 
====

If a release requires a review, you can schedule one by clicking the menu:Schedule a review[] link. 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. 

[NOTE]
====
The free-form text field in the review record is intended for other types of reviews (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.

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 https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev[cross-project-issues-dev mailing list] (the EMO monitors this 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::[]

[[pmi-faq]]
=== Frequently Asked Questions

[qanda]

Why doesn't a committer appear on the project's _Who's Involved_ page? ::

For a committer to appear on a project's _Who's Involved_ page:
+
--
. The new committer must be <<elections-committer,elected>> (or be listed as an initial committer on a <<starting-proposal,project proposal>>);
. The election must complete successfully and be approved by the PMC;
. The new committer must provide the required <<paperwork,paperwork>>;
. The paperwork must be processed by the EMO Records Team; and
. The webmaster must create the committer account.
--
+
Each piece takes time. If a committer doesn't appear some number of days after the successful completion of a committer election, then contact the committer to confirm that they've followed the provided instructions and have submitted committer paperwork. Then, connect with mailto:{emoEmail}[EMO] for assistance.
+
If the new committer will be working with projects that use GitHub, they must be sure to add their GitHub Id to their <<contributing-account,Eclipse Foundation Account>> so that our scripts can add them to the GitHub Teams that we use to manage access to Eclipse Foundation repositories hosted on GitHub.

What is the difference between a _Committer_ and an _Historic Committer_? ::

The _Who's Involved_ page lists committers and (in many cases) historic committers. Committers are those individuals who currently hold committer status (i.e., they can write to project resources). Historic committers are retired former committers. While they hold a special place in our hearts, they have no official status on the project. To turn an historic committer back into a committer, they must be <<elections-committer,re-elected>> to the project.