handbook/polarsys.book.xml

<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc?>
<?asciidoc-numbered?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>PolarSys Project Handbook</title>
<date>2015-08-18</date>
</info>
<preface>
<title></title>
<simpara>Copyright &#169; 2015 Eclipse Foundation, Inc., Made available under the Eclipse Public License v 1.0</simpara>
</preface>
<chapter xml:id="preamble">
<title>Overview</title>
<simpara>This document provides you with the information that you need to
create a new PolarSys open source project or become a committer
on an existing one.</simpara>
<simpara>While this document is focused on PolarSys, it makes several
"Eclipse" references, including the <emphasis>Eclipse Foundation</emphasis>,
<emphasis>Eclipse Development Process</emphasis>, and <emphasis>Eclipse Management Organization</emphasis>.
The Eclipse Foundation is the legal entity that manages the operations
of the PolarSys working group, software development forge, and community.
Many of the provided services and contacts are so-named on
that basis.</simpara>
<simpara>The <link xlink:href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</link> (EDP) is the foundational
document for PolarSys projects and committers. It describes the
manner in which we do open source software. The Eclipse Development
Process does not prescribe any particular development methodology;
it is more concerned with the larger-scale aspects of open source
project lifecycle, including such things as reviews, processes for
running votes and elections, bringing new committers onto a project, etc.
This document will elaborate on some key points of the Eclipse Development
Process.</simpara>
<section xml:id="preamble-principles">
<title>Principles</title>
<simpara>Four basic principles lie at the heart of the Eclipse Development Process:</simpara>
<itemizedlist>
<listitem>
<simpara>Transparency;</simpara>
</listitem>
<listitem>
<simpara>Openness;</simpara>
</listitem>
<listitem>
<simpara>Meritocracy; and</simpara>
</listitem>
<listitem>
<simpara>Vendor neutrality</simpara>
</listitem>
</itemizedlist>
<simpara>We refer to the first three as the "open source rules of engagement".</simpara>
<simpara>To operate with <emphasis role="strong">transparency</emphasis>, a project&#8217;s discussions, minutes, deliberations,
project plans, plans for new features, and other artifacts are open, public,
and easily accessible.</simpara>
<simpara><emphasis role="strong">Openness</emphasis> at PolarSys means quite a lot more than "open book" (which is
really a synonym for transparent). The project is open to all;
PolarSys provides the same opportunity to all. Everyone participates
with the same rules; there are no rules to exclude any potential contributors
which include, of course, direct competitors in the marketplace.</simpara>
<simpara>PolarSys is a <emphasis role="strong">meritocracy</emphasis>. The more that somebody contributes, the more
responsibility they will earn. A pattern of quality contribution to a project
may lead to an invitation to join the project as a committer. Leadership roles
in PolarSys are also merit-based and earned by peer acclaim. Merit must be
demonstrated in publicly-accessible forums. Committers and project leads are
added to a project via <link linkend="elections">election</link>.</simpara>
<note>
<simpara>Employment status has no bearing at whether or not somebody can participate
in an open source project at PolarSys. Employment does not guarantee
committer status; committer status must be earned by everybody.</simpara>
</note>
<simpara><emphasis role="strong">Vendor neutrality</emphasis> is similar to openness in that it&#8217;s concerned with
maintaining a level playing field. No vendor is permitted to dominate a project,
and nobody can be excluded from participating
in a project based on their employment status. While
project resources will contain copyright statements that assert ownership of
various assets by individual vendors, the project itself must remain vendor
neutral.</simpara>
<simpara>Quality and intellectual property cleanliness are also important principles.</simpara>
<simpara><emphasis role="strong">Quality</emphasis> means extensible frameworks and exemplary tools developed in an open,
inclusive, and predictable process involving the entire community. From the
consumption perspective, PolarSys quality means good for users (exemplary tools
are cool/compelling to use, indicative of what is possible) and ready for
use by adopters. From the creation perspective, PolarSys quality means working
with a transparent and open process, open and welcoming to participation from
technical leaders, regardless of affiliation.</simpara>
<simpara><emphasis role="strong"><link linkend="ip">Intellectual property</link></emphasis> (IP) is any artifact that is made available from
a PolarSys server (this includes source code management systems, the website,
and the downloads server). Artifacts include (but are not limited to) such things
as source code, images, XML and configuration files, documentation, and more.
Strict rules govern the way that we manage IP and your responsibilities
as a committer.</simpara>
<simpara>Code produced by an PolarSys project is used by organizations to build products.
These adopters of PolarSys technology need to have some assurance that the IP they&#8217;re
basing their products on is <emphasis role="strong">clean</emphasis>: the organization or individuals who claim
copyright of the code are the legitimate copyright holders, and the copyright
holders legitimately agree to make the code available under the license(s) that
the project works under. As a committer, you must be careful that you do not copy
code and inadvertently claim it as your own.</simpara>
</section>
</chapter>
<chapter xml:id="starting">
<title>Starting an Open Source Project at PolarSys</title>
<simpara>PolarSys open source projects start with a proposal that is made
available to the community for review. At the end of the <emphasis>community
review</emphasis> period, we engage in a <emphasis>creation review</emphasis>, and then
provision the project resources.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/project-creation.png"/>
</imageobject>
<textobject><phrase>An overview of the Project Creation Process</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>Use the <link xlink:href="https://www.polarsys.org/node/add/project-proposal">web form</link> to create a new project proposal.
Instructions are provided on the form. All new proposals are created
in <emphasis>draft</emphasis> mode, and are accessible only by the original author and
anybody designated as a project lead or committer in the proposal.
Only those individuals designated as a project lead may edit the
proposal.</simpara>
<note>
<simpara>Keep track of the URL of the proposal. We do not provide
public links to the document until after the proposal is opened for
community review.</simpara>
</note>
<simpara>A proposal must minimally include a description of the project, a
declaration of scope, and a list of prospective members (project
leads and committers) before we make it accessible to the public
for <emphasis>community review</emphasis>.</simpara>
<simpara>When you feel that the proposal is ready, send a note to
the Eclipse Management Organization (EMO) at <link xlink:href="mailto:emo@eclipse.org">emo@eclipse.org</link> requesting that
the proposal be made available to the public for review. The EMO
will review the proposal and may provide feedback before initiating
the <emphasis>community review</emphasis> period.</simpara>
<simpara>At the beginning of the <emphasis>community review</emphasis> period, the EMO will
announce the proposal on several channels (the <link xlink:href="http://www.eclipse.org/projects/project_activity.php">Project
Activity News</link> page, Twitter, the
<link xlink:href="http://www.eclipse.org/forums/eclipse.proposals">Proposals Forum</link>, blog post, and an email note
to the Eclipse Foundation members and committers). The EMO will
also open an record in the Eclipse Foundation&#8217;s issue tracker&#8212;&#8203;an
instance of Bugzilla&#8212;&#8203;to track the progress of the proposal;
the proposal&#8217;s author and project leads will be copied on that record.</simpara>
<simpara>A proposal will be open for community review for a minimum of two
weeks.</simpara>
<simpara>The Eclipse Foundation holds the <emphasis>trademark</emphasis> for all PolarSys projects.
Trademark assignment is undertaken prior to the creation of any new
project. If you already have a trademark on your project name, that
trademark must be assigned to the Eclipse Foundation. Be advised that
trademark assignment can be a time-consuming process (it can take hours,
days, or weeks depending on the circumstances surrounding the name).
If you currently hold the trademark, you will be asked to complete a
<link xlink:href="http://eclipse.org/legal/Trademark_Transfer_Agreement.pdf">Trademark Transfer Agreement</link>.</simpara>
<simpara>The proposal must list two mentors from the Architecture Council.
Members of the Architecture Council have considerable experience with
Eclipse Foundation practices, and the <link xlink:href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</link>.
If you are already in contact with mentors who agree to help you with
your project, please do list them in the proposal. Otherwise, the
EMO will engage directly with the Architecture Council to identify
mentors as necessary. Mentors are available to the project through the
incubation phase; they are released from their duties when the project
<link linkend="release-graduation">graduates</link>.</simpara>
<simpara>When the project name trademark has been secured, mentors have been
identified, and the proposal contents are finalized, the EMO will schedule
a <emphasis>creation review</emphasis>. Reviews&#8212;&#8203;which run for a minimum of one week&#8212;&#8203;are
scheduled twice a month, generally concluding on the first and third
Wednesday of each month. The creation review may overlap with the
<emphasis>community review</emphasis> period.</simpara>
<note>
<simpara>Creation reviews tend to always be successful. They should be
considered low stress as the hard work has already been done in
advance of the start of the review.</simpara>
</note>
<simpara>Following the creation review, the EMO will initiate the provisioning process.
To gain committer status, some <link linkend="paperwork">committer paperwork</link> must be completed
as part of the provisioning process. The exact nature of that
paperwork depends on several factors, including the employment status
of the individual and the Eclipse Foundation membership status of their employer.</simpara>
<note>
<simpara>If you can be ready with the paperwork in time for the completion of the
creation review, then we can move quickly through the provisioning process.
When we initiate provisioning, committers will be sent an email with
instructions; please don&#8217;t send any paperwork in until after you receive
those instructions.</simpara>
</note>
<section xml:id="starting-after-provisioning">
<title>After Provisioning</title>
<simpara>The Webmaster will send a note announcing the completion of the provisioning
process. Before you commit any code into your project repository, you must
submit your project&#8217;s <link linkend="ip-initial-contribution"><emphasis>initial contribution</emphasis></link> and
list of third-party libraries for review by the IP team.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/post-creation.png"/>
</imageobject>
<textobject><phrase>Post creation activities</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>Do not commit any code to your project&#8217;s source code repository until after
you receive approval for the IP Team. Once you&#8217;ve received that approval,
you can do builds and produce milestones for your first release. You must
wait until after the IP Team has approved your initial contribution and use
of third-party libraries before you do any official <link linkend="release">releases</link>.</simpara>
</section>
<section xml:id="starting-project-phases">
<title>Project Phases</title>
<simpara>All new projects start in the <emphasis>incubation phase</emphasis> (a project in the
incubation phase is said to be <emphasis>incubating</emphasis>). The classification of
a project in the incubation phase is not a statement about the quality
of the project&#8217;s code; rather, incubation phase is more about the
project team&#8217;s progress in practicing the open and public processes
necessary to establish the three communities (developers, adopters,
and users) around the project.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/Egg-incubation.png"/>
</imageobject>
<textobject><phrase>The Incubation Logo</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>In order to alert potential consumers of the incubating nature,
projects in the incubation phase must include <emphasis>incubation branding</emphasis>:</simpara>
<itemizedlist>
<listitem>
<simpara>Display the incubation logo on their project web page (if they have one);</simpara>
</listitem>
<listitem>
<simpara>Displays the incubation logo on their project&#8217;s primary download page;</simpara>
</listitem>
<listitem>
<simpara>Include the word "incubation" in the filename of all downloadable
files (when technically feasible) for builds and milestones;</simpara>
</listitem>
<listitem>
<simpara>When technically feasible, include the word "incubation" in features
(e.g. about dialogs, feature lists, and installers).</simpara>
</listitem>
</itemizedlist>
<simpara>There are no incubation branding requirements for general
user interface elements.</simpara>
<simpara>For projects that produce OSGi artifacts, include the word
"incubation" in the <emphasis>Bundle-Name</emphasis>, feature names, and p2 repositories.</simpara>
<note>
<simpara>The word "incubation" should not be included in technical
namespaces (especially when it may result in confusion when the project
leaves incubation). e.g. an OSGi bundle&#8217;s <emphasis>Bundle-SymbolicName</emphasis>, or a
Java package name.</simpara>
</note>
<simpara>Incubating projects that correctly conform to the incubation branding
rules outlined above may take advantage of the <link linkend="ip-parallel-ip">Parallel
IP Process</link>. They are encouraged to produce milestone builds, make
releases, and grow their community.</simpara>
<simpara>When the project code is ready (e.g. stable APIs) and the project team
has learned to operate as an open source project according to the
Eclipse Development Process, the project may opt to <emphasis>graduate</emphasis> into
the <emphasis>mature phase</emphasis>.</simpara>
<simpara>Most of the lifetime of a PolarSys project is spent in the mature phase.
A mature project is one that is a good open source citizen with open,
transparent, and meritocractic behavior. The project is regularly
and predictably releasing IP clean extensible frameworks and
exemplary tools. The project is actively nurturing the three
communities: developers, adopters, and users.</simpara>
</section>
<section xml:id="starting-faq">
<title>Frequently Asked Questions</title>
<qandaset>
<qandaentry>
<question>
<simpara>How do I find Architecture Council mentors? </simpara>
</question>
<answer>
<simpara>You don&#8217;t have to find them yourself. Focus on the content of the
proposal. We can solicit mentors from the Architecture Council after
the proposal has been opened for community review.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Can I change the proposal after it is posted? </simpara>
</question>
<answer>
<simpara>Yes. The proposal can be changed any time before the start of the
start of the creation review.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>When do I submit my code for review by the IP team? </simpara>
</question>
<answer>
<simpara>Submit your code (initial contribution) for review after the project
has been provisioned. The Eclipse Webmaster will let you know via
email when provisioning is complete.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Does the new project have to use Git? </simpara>
</question>
<answer>
<simpara>Yes. Git is the only source code management system that is currently
permitted for new projects.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Can I host my project code on GitHub? </simpara>
</question>
<answer>
<simpara>New projects can make use of <link linkend="resources-github">GitHub</link>. Official project repositories
must be moved under the <link xlink:href="https://github.com/polarsys">PolarSys Organization</link> at GitHub.
Official repositories are subject to the same intellectual
property due diligence rules and processes that all Eclipse project
repositories must follow.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How long should I let my project incubate? </simpara>
</question>
<answer>
<simpara>It depends. Community expectations are one factor. Team experience
with open source is another. If your team is new to open source,
it may make sense to stay in incubation a little longer than a
seasoned team with a mature code base might. As a general rule,
though, projects should plan to leave incubation within a year.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Does the mature project code that I&#8217;m bring to PolarSys need to incubate? </simpara>
</question>
<answer>
<simpara>Yes. All new projects start in the incubation phase. Remember
that incubation is as much about the project team learning about
how to operate as an open source project as it is about the
project code. Project teams that "get it" can opt to exit
incubation quickly (e.g. with their first release) if that
makes sense for the team and the community.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What do all these terms (e.g. EMO) mean? </simpara>
</question>
<answer>
<simpara>Please see the <link linkend="glossary">glossary</link>.</simpara>
</answer>
</qandaentry>
</qandaset>
</section>
</chapter>
<chapter xml:id="project-resources-and-services">
<title>Project Resources and Services</title>
<simpara>Open source projects at the Eclipse Foundation are required to make use
of certain Eclipse Foundation services:</simpara>
<itemizedlist>
<listitem>
<simpara>All project issues must be tracked in the <link xlink:href="https://www.polarsys.org/bugs">PolarSys Bugzilla</link>
instance;</simpara>
</listitem>
<listitem>
<simpara>Source code must be maintained in source code repositories assigned to the
project (e.g. a PolarSys <link xlink:href="https://git.polarsys.org/c">Git</link> or <link xlink:href="https://git.polarsys.org/r">Gerrit</link> instance,
or the <link xlink:href="https://github.com/polarsys">PolarSys Organization</link> on GitHub);</simpara>
</listitem>
<listitem>
<simpara>All third-party libraries used by the project must be tracked and
approved for use by the Eclipse IP Team;</simpara>
</listitem>
<listitem>
<simpara>Downloads must be distributed via a forge-specific downloads server;</simpara>
</listitem>
<listitem>
<simpara>Developer (committer) communication must occur in the <emphasis>dev</emphasis> list
provided to the project by the Eclipse; and</simpara>
</listitem>
<listitem>
<simpara>Projects must keep their <link linkend="pmi-metadata">Project Metadata</link> up-to-date.</simpara>
</listitem>
</itemizedlist>
<section xml:id="resources-source">
<title>Source Code Management</title>
<simpara>Your project must maintain source code in the repositories assigned to the
project by the Eclipse Foundation. These official repositories must be
the exclusive source of all project code delivered via the project&#8217;s assigned
distribution channel (e.g. the download server).</simpara>
<simpara>In order for your project to operate in an <emphasis>open</emphasis> manner, it must be possible
for potential contributors to have access to the code base in its most current
form, so all ongoing development must be regularly pushed to these canonical
repositories.</simpara>
<section xml:id="resources-cla">
<title>Contributor License Agreement (CLA)</title>
<simpara>The Eclipse Foundation has implemented <link xlink:href="https://www.eclipse.org/legal/CLA.php">Contributor License Agreements</link> (CLA)
to improve <link linkend="ip">intellectual property</link> (IP) management and workflow. All
contributors, who are not committers on the PolarSys project, must sign the CLA.</simpara>
<simpara>You do <emphasis role="strong">not</emphasis> require a CLA to contribute to a project on which you have committer
status.</simpara>
</section>
<section xml:id="resources-commit">
<title>Git Commit Records</title>
<simpara>Git commit records are required to take a specific form. The credentials
of the actual author must be used to populate the <literal>Author</literal> field. The email
address used must match the email address that the Eclipse Foundation has
on file for the author (case-sensitive).</simpara>
<simpara>The commit message is divided into three sections:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>One line (max 72 characters) summary;</simpara>
</listitem>
<listitem>
<simpara>Description; and</simpara>
</listitem>
<listitem>
<simpara>Footer.</simpara>
</listitem>
</orderedlist>
<formalpara>
<title>Example Git Commit Record</title>
<para>
<screen>commit d6cf52411377a039fc2906378711091a26e932cb
Author: Some Body &lt;somebody@somewhere.com&gt; <co xml:id="CO1-1"/>
Date:   Wed May 29 16:17:36 2013 +0200

    Bug 350686 - Hide unwanted action bar items <co xml:id="CO1-2"/>

    This change hides unwanted 'Link with Editor' and
    'Customize View...' items from the local toolbar
    and the view menu.

    Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7 <co xml:id="CO1-3"/>
    Also-by: Some Bodyelse &lt;somebodyelse@nowhere.com&gt; <co xml:id="CO1-4"/>
    Signed-off-by: Some Body &lt;somebody@somewhere.com&gt; <co xml:id="CO1-5"/></screen>
</para>
</formalpara>
<calloutlist>
<callout arearefs="CO1-1">
<para>The email address of the author must match the email address on the Eclipse Foundation account.</para>
</callout>
<callout arearefs="CO1-2">
<para>Best practice: include the bug id in the commit message summary.</para>
</callout>
<callout arearefs="CO1-3">
<para>Gerrit change id (only when pushing to Gerrit for review).</para>
</callout>
<callout arearefs="CO1-4">
<para>Additional authors can be added using <literal>Also-by</literal> entries.</para>
</callout>
<callout arearefs="CO1-5">
<para>Non-committers must <emphasis>sign-off</emphasis> the commit using the same email address as used in the author field.</para>
</callout>
</calloutlist>
<simpara>The <emphasis>summary</emphasis> line is used in many places where Git commits are listed, ensure
that this line is sensible by itself. The <emphasis>description</emphasis> area should be used to provide
more detail about the commit. The footer area is used for extra fields and values.</simpara>
<simpara>If the bug id is included in the summary line (using the form "Bug 12345 - xxx" or "[12345] xxx")
Gerrit Code Review will automatically add a link in the
corresponding Bugzilla record back to the Gerrit record (this, of course, only
applies to commits pushed to Gerrit).</simpara>
<simpara>The <literal>Change-Id</literal> is used by <link linkend="resources-gerrit">Gerrit Code Review</link> to associate new versions
of a change back to its original review. This field need only be specified if the
repository is managed by Gerrit.</simpara>
<simpara>Create a separate <literal>Also-by</literal> field for each additional author of a commit. This might
apply, for example, if a commit has been authored via pair-programming, or the commit
is the result of collapsing multiple commits authored by multiple developers.</simpara>
<simpara>Commits that are provided by non-committers must have a <literal>Signed-off-by</literal> field in the
footer indicating that the author is aware of the terms by which the contribution has been
provided to the project. The non-committer must additionally have an Eclipse Foundation
account and must have a signed <link linkend="resources-cla">Contributor License Agreement</link> (CLA)
on file.</simpara>
</section>
<section xml:id="resources-git">
<title>Git</title>
<simpara>Those projects that want to use Git on the PolarSys forge, are assigned a
directory in which they may create as many Git repositories as required.
<link xlink:href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&amp;component=Git">Open a bug</link> to request that the Webmaster create a new Git
repository for your project. Alternatively, committers with shell accounts
can create repositories themselves.</simpara>
<formalpara>
<title>Create a new Git repository</title>
<para>
<screen>> initrepo /gitroot/project/org.polarsys.repo.name.git</screen>
</para>
</formalpara>
<simpara>For consistency, the name of the repository must end with <literal>.git</literal>.</simpara>
<simpara>To set the description of the repository, use <literal>sftp</literal> or <literal>scp</literal> to copy a text file to
<literal>/gitroot/project/org.polarsys.repo.name.git/description</literal>. Git repository
descriptions should be limited to a paragraph of one or two sentences.</simpara>
<simpara>Only project committers can push to a PolarSys Git repository. A push
that includes commits that do not conform to the required form will be rejected.</simpara>
<simpara>You can <link xlink:href="https://git.polarsys.org/c">browse PolarSys repositories</link> directly on the Git server.</simpara>
</section>
<section xml:id="resources-gerrit">
<title>Gerrit Code Review</title>
<simpara><link xlink:href="https://www.gerritcodereview.com/">Gerrit</link> provides web based code review and
repository management for the Git version control system. Many projects use
Gerrit to reduce barriers and encourage contribution to the project.
<link xlink:href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&amp;component=Gerrit">Open a bug</link> to request that the Webmaster configure your
Git repository for Gerrit.</simpara>
<simpara>Commits may be pushed directly to the Git repository through Gerrit by
a project committer (e.g. to the <literal>master</literal> branch).</simpara>
<simpara>Anybody can push to a <literal>refs/for/*</literal> branch for review in a Gerrit repository. A push
that includes commits that do not conform to the required form will be rejected.
Commits intended for review should have a
<link xlink:href="https://git.eclipse.org/r/Documentation/user-changeid.html"><literal>Change-Id</literal></link></simpara>
<simpara>You can <link xlink:href="https://git.polarsys.org/r">browse PolarSys repositories</link> directly on the Gerrit
server.</simpara>
</section>
<section xml:id="resources-github">
<title>GitHub</title>
<simpara>Projects may opt to move some or all of their canonical source code repositories to the
<link xlink:href="https://github.com/polarsys">PolarSys organization</link> on GitHub.</simpara>
<note>
<simpara>Projects that host source code on GitHub are not permitted to use GitHub
Issues or Wiki.</simpara>
</note>
<simpara><link xlink:href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&amp;component=GitHub">Open a bug</link> to request that the Webmaster create a new, or move
an existing, Git repository for your project. The Webmaster will install some
<emphasis>hooks</emphasis> on your GitHub repository.</simpara>
<simpara>The <emphasis>Committers hook</emphasis> grants designated project committers write access to the
GitHub-hosted project repositories. Project committers must use the email address they
provide to the Eclipse Foundation as their GitHub email address.</simpara>
<simpara>The <link linkend="resources-cla">Contributor License Agreement</link> (CLA) hook will inspect incoming
GitHub pull requests to ensure that the contributor has a valid CLA on file, and that
the commit has been "signed-off" as required. Project committers should only merge pull
<emphasis>green</emphasis> requests:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/Github-cla-success.png"/>
</imageobject>
<textobject><phrase>Github cla success</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>The GitHub API does not give us a means of absolutely denying a merge; all we can
do is warn you that the contributors have not signed a CLA:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/Github-cla-failure.png"/>
</imageobject>
<textobject><phrase>Github cla failure</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>Do not merge unless you are absolutely certain that the contributer does have a
valid CLA on file (e.g. the Contributor License Agreement Lookup Tool confirms
that they have a CLA).</simpara>
<simpara>You must manually check that the commit message includes the
required "Signed-off-by" statement in the footer.</simpara>
<simpara>The Webmaster creates and maintains a mirror of all GitHub-hosted
repositories on Eclipse Foundation hardware.</simpara>
</section>
</section>
<section xml:id="resources-libraries">
<title>Third-party Libraries</title>
<simpara>PolarSys projects must register all of their <link linkend="ip-third-party">third-party library</link> use with the
IP Team.</simpara>
</section>
<section xml:id="resources-forums">
<title>Forums and Outbound Communication</title>
<simpara>All projects are assigned a <link xlink:href="http://www.polarsys.org/forums">user forum</link> as a point of contact between
the user and adopter communities, and the project developers.</simpara>
<simpara>The EMO strongly encourages the use of alternative communication channels for
connecting with the community: your project team knows your community and how
to best connect with them.</simpara>
</section>
<section xml:id="resources-website">
<title>Project Websites</title>
<simpara>Project websites are an excellent way to connect your project with
your community. Many projects opt to use the <link linkend="pmi">Project Management Infrastructure</link>
(PMI) as their project website,
but if so-desired, a project may host a website on Eclipse Foundation-hosted
servers.</simpara>
<simpara>Project website sources are hosted in Git repositories maintained by the
Eclipse Foundation. <link xlink:href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&amp;component=Website">Open a bug</link> to request that the Webmaster
create a website for your project.</simpara>
<note>
<simpara>Alternative hosting services for project-specific websites are
not permitted. Websites <emphasis>not</emphasis> hosted by the Eclipse Foundation are
considered third-party and so are subject to the
<link xlink:href="https://eclipse.org/legal/logo_guidelines.php">Guidelines for Eclipse
Logo &amp; Trademarks</link> (the Eclipse foundation asserts ownership of the
project name trademark).</simpara>
</note>
</section>
<section xml:id="resources-builds">
<title>Builds</title>
<simpara>Use of Eclipse Foundation-provided and hosted build services, the so-called
<link xlink:href="http://wiki.eclipse.org/CBI">Common Build Infrastructure</link> (CBI) is strongly recommended, but n
ot strictly required.</simpara>
<simpara>Whether or not your project chooses to make use of provided build resources, it must
be possible for members of the community to build project artifacts from
source code with reasonable effort.</simpara>
<section xml:id="resources-signing">
<title>Signed Artifacts</title>
<simpara>Where technically sensible, all downloadable artifacts should
be <link xlink:href="https://wiki.eclipse.org/JAR_Signing">signed</link> by an Eclipse Foundation-provided certificate.</simpara>
</section>
</section>
<section xml:id="resources-downloads">
<title>Downloads</title>
<simpara>Project artifacts (e.g. downloads) can be distributed via third-party
services (e.g. Maven Central), but the Eclipse Foundation-provided
infrastructure must be considered the primary source of project
downloads.</simpara>
<simpara>Project committers can <link xlink:href="https://wiki.eclipse.org/IT_Infrastructure_Doc#Downloads">upload project artifacts</link> to the project&#8217;s
directory on the download server.</simpara>
</section>
</chapter>
<chapter xml:id="paperwork">
<title>Committer Paperwork</title>
<simpara>The Eclipse Foundation needs to ensure that all committers with write
access to the code, web site, and issue tracking system understand their role in
safeguarding the intellectual property of PolarSys. The Eclipse Foundation also
needs to ensure that we have accurate records of the people who are
acting as change agents on the projects. To ensure that
committers understand their role, and that that Eclipse Foundation has
accurate records, committers must provide documentation asserting
that they have read, understood, and will follow the committer guidelines, and to have
their employer sign that they agree that the new committer
can participate at PolarSys and can contribute under the terms of the
project license.</simpara>
<simpara>All committers must complete the <emphasis>Committer Questionnaire</emphasis> and provide documentation
as described below.</simpara>
<section xml:id="paperwork-questionnaire">
<title>Committer Questionnaire</title>
<simpara>The <link xlink:href="http://portal.eclipse.org">Committer Questionnaire</link> is an online form that
must be completed by all new committers. This form offers two separate paths:
one for committers who work for a member company that has provided a signed
Member Committer Agreement, and one for everybody else.</simpara>
<note>
<simpara>The <emphasis>Committer Questionnaire</emphasis> is accessible only after you have been elected as
a committer on a project, either as an initial committer on a new project, or
via election on an existing project.</simpara>
</note>
<simpara>Only member companies that have provided a signed Member Committer Agreement
will be listed as member companies in the Committer Questionnaire.</simpara>
</section>
<section xml:id="paperwork-documents">
<title>Documents</title>
<simpara>The exact nature of the documentation required is dependent on your
employments status.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/paperwork.png" width="75%" scalefit="1"/>
</imageobject>
<textobject><phrase>Paperwork requirements flowchart.</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>Documents must be printed, signed and then returned either by fax
(using the fax number on the form) or as scanned images via email
to <link xlink:href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</link>.</simpara>
<section xml:id="paperwork-mca">
<title>Member Committer Agreement</title>
<simpara>The <link xlink:href="http://www.eclipse.org/legal/committer_process/EclipseMemberCommitterAgreementFinal.pdf">Member Committer Agreement</link> (MCA) is used by member companies to
cover all of their employees who participate in Eclipse Foundation projects
as committers.</simpara>
<simpara>If your employer has provided a signed MCA, then you most likely do not
require any additional paperwork.</simpara>
<note>
<simpara>MCAs make committer paperwork easy, especially if you
work for a member company that employs multiple committers. With an MCA a
company can provide signed documentation once, rather than once for each
employee (as required for an Individual Committer Agreement).</simpara>
</note>
<simpara>If your employer has not already provided an MCA, consult with your management
team to determine who has the necessary authority to sign it on your company&#8217;s
behalf. Provide the MCA in advance of the completion of your committer election
or new project creation to streamline the committer provisioning process.
If you and your management team are not sure whether or
not your employer has an MCA, ask <link xlink:href="mailto:emo-records@eclipse.org">EMO Records</link>.</simpara>
<simpara>If your employer is a member company that cannot provide a signed
MCA, then you&#8217;ll have to complete an Individual Committer Agreement and
Eclipse Committer Employer Consent Form.</simpara>
</section>
<section xml:id="paperwork-ica">
<title>Individual Committer Agreement</title>
<simpara>The Individual Committer Agreement (ICA) greement is used by committers
who are not covered by an Member Committer Agreement.</simpara>
<simpara>You will need to provide an ICA if:</simpara>
<itemizedlist>
<listitem>
<simpara>You work for member company that has not signed a Member Committer Agreement;</simpara>
</listitem>
<listitem>
<simpara>You work for a company that is not a member of the Eclipse Foundation;</simpara>
</listitem>
<listitem>
<simpara>You are self employed or not employed; or</simpara>
</listitem>
<listitem>
<simpara>You are a student.</simpara>
</listitem>
</itemizedlist>
<simpara>If you provide an Individual Committer Agreement, and are employed
or self-employed, then you also need an <emphasis>Eclipse Committer Employer</emphasis>
Consent Form.</simpara>
</section>
<section xml:id="paperwork-ececf">
<title>Eclipse Committer Employer Consent Form</title>
<simpara>Committers covered by an Individual Committer Agreement must document
the consent of their employer when participating in Eclipse Foundatio
projects by providing an Eclipse Committer Employer Consent Form (ECECF).</simpara>
<simpara>You will need to provide an <link xlink:href="http://www.eclipse.org/legal/committer_process/employer_consent.pdf">ECECF</link> if:</simpara>
<itemizedlist>
<listitem>
<simpara>You work for member company that has not signed a Member Committer Agreement;</simpara>
</listitem>
<listitem>
<simpara>You work for a company that is not a member of the Eclipse Foundation; or</simpara>
</listitem>
<listitem>
<simpara>You are self-employed.</simpara>
</listitem>
</itemizedlist>
<simpara>If you are self employed, an owner of your own company, or
have full ownership or part ownership in another company and has the
authority to sign and submit the  Eclipse Committer Employer Consent Form
on your own behalf, then they should do so.</simpara>
<simpara>Alternatively, you may arrange for the company that is
your principal business customer to sign and submit the
Eclipse Committer Employer Consent Form on your behalf.</simpara>
</section>
</section>
<section xml:id="paperwork-existing">
<title>Existing Committer</title>
<simpara>If you are already a committer on an existing Eclipse Foundation project then
additional paperwork may or may not be needed. The EMO IP Team will ask for
additional documentation if required.</simpara>
<simpara>If that MCA or ECECF already explicitly covers you for the
new project, or that MCA or ECECF is universal (for all projects),
then no additional paperwork is required</simpara>
<simpara>If you are covered by an MCA or ECECF that does not include
the new project, then the candidate must provide the documents as described
above.</simpara>
</section>
<section xml:id="paperwork-not-employed">
<title>Not Employed or Student</title>
<simpara>If you are not employed or are a student, send a note to <link xlink:href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</link>
explaining your not employed or student status.</simpara>
<note>
<simpara>We require this email because most new committers are employed by a company,
the Eclipse Legal Team assumes that is the case for everyone, thus exceptions
need to be noted.</simpara>
</note>
</section>
<section xml:id="paperwork-faq">
<title>Frequently Asked Questions</title>
<qandaset>
<qandaentry>
<question>
<simpara>What happens if I do not fill out the paperwork?</simpara>
</question>
<answer>
<simpara>Then you don&#8217;t get your login and password for write-access to the
source code repository(s). Sorry. No exceptions.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What happens if I cannot convince my employer to fill out the paperwork?</simpara>
</question>
<answer>
<simpara>The Eclipse Board of Directors has taken a firm position that if you are
employed then you must meet one of the scenarios described above. If you cannot
convince your employer to fill out the necessary paperwork, then you may
not have write-access to project resources. This is the
Board&#8217;s position <emphasis>even if</emphasis> you are working on PolarSys projects on your
own time. We realize that this prevents some talented and desirable
people from being able to commit to the projects but this is our
IP risk reduction strategy.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Where can I get help to discuss these documents with my management team? </simpara>
</question>
<answer>
<simpara>The EMO and the Executive Director are happy to talk to your management
and senior executives about these (and other) legal documents to
help them understand why these documents are the best risk reduction
solution for everyone involved (The Eclipse Foundation, you, and your
employer); just contact us at <link xlink:href="mailto:license@eclipse.org">license@eclipse.org</link>.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What formats can be used to submit paper documentation? </simpara>
</question>
<answer>
<simpara>The Eclipse Foundation accepts any of the following formats for
submitting a paper form:</simpara>
<itemizedlist>
<listitem>
<simpara>Print, sign, and postal mail the form to the Eclipse Foundation;</simpara>
</listitem>
<listitem>
<simpara>Print, sign, and fax the form to the Eclipse Foundation; or</simpara>
</listitem>
<listitem>
<simpara>Print, sign, scan, and email to the scan as an attachment to the Foundation</simpara>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What Email address should I use to send scanned documents? </simpara>
</question>
<answer>
<simpara>Email scans of the completed paperwork to EMO Records at <link xlink:href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</link>.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What if a committer changes employers? </simpara>
</question>
<answer>
<simpara>If you change employers, please contact <link xlink:href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</link>.</simpara>
</answer>
</qandaentry>
</qandaset>
</section>
</chapter>
<chapter xml:id="ip">
<title>Intellectual Property</title>
<simpara>PolarSys projects are expected to take necessary precautions to mitigate
intellectual property (IP) risk to adopters. A company that integrates the code
from your project, for example, does so with confidence that the code in the
project can legally be distributed under the agreed-to terms. The
<link xlink:href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">IP Due Diligence Process</link>, managed by the Eclipse IP Team
(commonly referred to as the <emphasis>IP Team</emphasis>), is in place to support this.</simpara>
<simpara>All PolarSys committers must be familiar with the <link xlink:href="http://eclipse.org/org/documents/Eclipse_IP_Policy.pdf">Eclipse IP
Policy</link>.</simpara>
<section xml:id="ip-initial-contribution">
<title>Initial Contribution</title>
<simpara>Code provenance tracking is critical (we need to know the source of all code
that ends up in our repositories). To that end, all new projects are required to
make an <emphasis>initial contribution</emphasis> before <emphasis role="strong">any</emphasis> code is committed to a project&#8217;s
source code repository.</simpara>
<simpara>The IP Team will review your initial contribution to ensure that the code can
distributed through a PolarSys property. The IP Team will review the code to
make sure that it hasn&#8217;t been copied inappropriately, that licenses are being
used correctly, and so forth. As part of this process, the IP Team  will
research the source of all code; depending on the size of the contribution, this
can be a time-consuming process.</simpara>
<note>
<simpara>A project cannot make a <link linkend="release">release</link> until the due diligence on
the IP contained in that release&#8212;&#8203;including project code contributions and
third-party libraries&#8212;&#8203;is complete.</simpara>
</note>
<simpara>Create a <link linkend="ip-cq">contribution questionnaire</link> to submit the initial contribution
for review by the IP Team.</simpara>
<simpara>The IP Team is not able to review the history of project code being moved to
a PolarSys project. The IP Team will review a snapshot of the project code and
that snapshot, the <emphasis>initial contribution</emphasis>, must be the first commit in the
PolarSys repository. If your project uses an existing GitHub repository, the
Webmaster team will help you obscure the the history into a hidden branch.</simpara>
</section>
<section xml:id="ip-project-code">
<title>Project Code Contributions</title>
<simpara>Some contributions of code to maintained by the project (i.e. committed to a
project source code repository and maintained by the project team) must be
reviewed by the IP Team. The <link xlink:href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">IP Due Diligence Process</link>
provides help to determine whether or not the contribution needs to be reviewed
by the IP Team. If you&#8217;re not sure, ask your project mentors or your PMC for
assistance.</simpara>
<simpara>All contributions of project code must be tracked in the project&#8217;s
<link linkend="ip-iplog">IP Log</link>.</simpara>
<simpara>Create a <link linkend="ip-cq">contribution questionnaire</link> to submit a project code
contribution for review by the IP Team.</simpara>
</section>
<section xml:id="ip-third-party">
<title>Third-Party Libraries</title>
<simpara>All third-party libraries required by project code will have to be checked
and approved by the IP Team.</simpara>
<simpara>The IP Team must review a third-party library if:</simpara>
<itemizedlist>
<listitem>
<simpara>the Java/OSGi manifest for one of the project bundles makes a
direct reference to a third-party library (either the library bundle
or a package from the library);</simpara>
</listitem>
<listitem>
<simpara>project code includes an import statement for a package from a
third-party library;</simpara>
</listitem>
<listitem>
<simpara>project code uses reflection or other means to reference a
library&#8217;s APIs and implementation;</simpara>
</listitem>
<listitem>
<simpara>project code uses OSGi Services to make a reference to a
specific implementation of a service; or</simpara>
</listitem>
<listitem>
<simpara>project code invokes a "command line" tool.</simpara>
</listitem>
</itemizedlist>
<simpara>This list is not intended to be exhaustive.</simpara>
<simpara>The <link xlink:href="http://www.eclipse.org/org/documents/Eclipse_Policy_and_Procedure_for_3rd_Party_Dependencies_Final.pdf">Guidelines for the Review of Third Party Dependencies</link> can help
you determine how to classify your third-party libraries.</simpara>
<note>
<simpara>A project cannot make a <link linkend="release">release</link> until the due diligence on
the IP contained in that release&#8212;&#8203;including project code contributions and
third-party libraries&#8212;&#8203;is complete.</simpara>
</note>
<simpara>Create a <link linkend="ip-cq">contribution questionnaire</link> to submit a third-party
library for review by the IP Team.</simpara>
</section>
<section xml:id="ip-ownership">
<title>Ownership</title>
<simpara>The author of a contribution (or their employer) retains ownership of the
intellectual property contained in the contribution. As part of the contribution
process, the contributor licenses their contribution under the project license.</simpara>
</section>
<section xml:id="ip-copyright-headers">
<title>Copyright and License Headers</title>
<simpara>All source files must include a file header that describes the copyright and
license terms of the software.</simpara>
<formalpara>
<title>Example Copyright and License Header</title>
<para>
<screen>/*******************************************************************************
 * Copyright (c) 2015 Schmedly Inc. and others. <co xml:id="CO2-1"/>
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html <co xml:id="CO2-2"/>
 *
 * Contributors:
 *   Wayne Beaton - initial API and implementation <co xml:id="CO2-3"/>
 *******************************************************************************/</screen>
</para>
</formalpara>
<calloutlist>
<callout arearefs="CO2-1">
<para>Name the initial copyright owner; this must be a legal entity (e.g. a company or individual).
If other organizations have contributed, include "and others".</para>
</callout>
<callout arearefs="CO2-2">
<para>List project licenses.</para>
</callout>
<callout arearefs="CO2-3">
<para>Optionally list the names of the contributors and the nature of their contribution.</para>
</callout>
</calloutlist>
<simpara>Your project is not a legal entity and so it is inappropriate to list it as
the copyright owner.</simpara>
<warning>
<simpara>The copyright owner is either an individual or their employer. Most
employment contracts stipulate that the intellectual property creations of an
employee are the property of the employer and so the employer should generally
be listed as the copyright owner.</simpara>
</warning>
<simpara>For more information please see the <link xlink:href="https://www.eclipse.org/legal/copyrightandlicensenotice.php">Default Eclipse Foundation Copyright and License Notice</link>.</simpara>
</section>
<section xml:id="ip-licensing">
<title>Licensing</title>
<simpara>PolarSys top level projects define the standard licensing for their
projectsd. If your project has non standard licensing requirements,
you may need to make a presentation to the Eclipse board of directors
to request their approval. The presentation need only briefly describe
the project and why special licensing considerations are necessary.</simpara>
</section>
<section xml:id="ip-cq">
<title>Contribution Questionnaires</title>
<simpara>A Contribution Questionnaires (CQ) is the main interface
between PolarSys committers and the IP Team.</simpara>
<simpara>A CQ is started when a committer completes a <emphasis>questionnaire</emphasis> regarding
a contribution or third-party library. In literal terms, a CQ is a
record in a modified instance of Bugzilla, named <emphasis>IPZilla</emphasis>,
that tracks the progress of the approval process. The CQ record is the
primary communication channel between the submitting committer and the
IP Team. CQ records persist indefinitely.</simpara>
<note>
<simpara>You can review existing CQs via <link xlink:href="https://dev.eclipse.org/ipzilla">IPZilla</link>. Note that
IPZilla is accessible only by committers, Eclipse Foundation member company
represenatives, and other specifically-designated individuals.</simpara>
</note>
<simpara>All significant contributions of code to be maintained by a PolarSys project, as
defined by the Eclipse IP Due Diligence Process require a CQ.</simpara>
<simpara>Projects require a CQ for every third-party library that project
code makes direct use of (regardless of whether or not the library
is directly distributed by the project. If your code makes indirect
use of a third party library through another PolarSys
project&#8217;s code, you do not require a CQ for that library.</simpara>
<note>
<simpara>CQs for third-party libraries are <emphasis>version-specific</emphasis>. That is,
a separate CQ is required for different versions of the same library.</simpara>
</note>
<simpara>CQs are not generally required for ongoing work done by project
committers. Consult the IP Due Diligence Process document for
more information.</simpara>
<section xml:id="ip-parallel-ip">
<title>Parallel IP</title>
<simpara>The <emphasis>Parallel IP Process</emphasis> allows PolarSys projects to make use of
project code contributions and third-party libraries before they
are fully approved by the IP Team. In practical terms, the Parallel
IP Process permits&#8212;&#8203;with preliminary approval from the IP Team&#8212;&#8203;a
project to check-in code contributions into their source code
repository and run builds against third-party libraries
without having to wait for the full IP Due Diligence Process to
compete.</simpara>
<note>
<simpara>There is some risk associated with the Parallel IP Process.
The IP Team will grant preliminary approval based on a cursory
review of the contribution; but during their full review, they may
uncover issues that require mitigation. This may require, for
example, that some parts of a contribution be removed completely
(history and all) from a source code repository.</simpara>
</note>
<simpara>Parallel IP manifests in two different ways: projects in the
<emphasis>incubation phase</emphasis> may leverage the Parallel IP process for
project code and third-party libraries. <emphasis>Mature phase</emphasis> projects
may leverage parallel IP for new versions of third-party libraries
for which previous versions have already been approved.</simpara>
<simpara>To leverage the Parallel IP Process, projects still submit CQ.
The difference is that once a CQ has been reviewed for
license compatibility, the project will be authorized via IPzilla
to check-in the code start working on it.</simpara>
<simpara>All IP must be fully approved before it is included in a release.</simpara>
</section>
<section xml:id="ip-piggyback">
<title>Piggyback CQs</title>
<simpara>Many third party libraries have already been approved for use in PolarSys projects.
Many of those are immediately available via the <link xlink:href="http://www.eclipse.org/orbit">Orbit Project</link>.
While these libraries have already been cleared for use by all projects,
their use must be tracked. Usage is tracked so that&#8212;&#8203;in the event that a issue is uncovered
following the due diligence process&#8212;&#8203;we can mitigate the impact of that issue.</simpara>
<simpara>In this case, a <emphasis>piggyback CQ</emphasis> can be created on top of an existing CQ. Piggyback CQs
are generally approved very quickly as the due diligence work has already been completed.</simpara>
</section>
<section xml:id="ip-cq-workflow">
<title>CQ Workflow</title>
<simpara>The workflow for creating a CQ for a third-party library starts with a search of existing
CQs. If an existing CQ can be found that is concerned with the same library and version,
then a piggyback CQ is created. Piggyback CQs must be approved by the project&#8217;s Project
Management Committee (PMC) before they are processed by the EMO IP Team.</simpara>
<simpara>If an existing CQ cannot be found, a new one must be created. Once created, the source
code for the third-party library must be attached to the record. The PMC must then approve
the record. If the project is eligible to leverage the Parallel IP Process, the IP
Team performs a cursory review of the record and&#8212;&#8203;if the CQ meets with the
requirements&#8212;&#8203;tentatively approves the use of the library while the full review is
undertaken in parallel.</simpara>
<simpara>The IP team may require your assistance as it performs a deep analysis of the library.
Once that analysis is complete and the IP team has made a decision, they will outline
the next steps. These next steps may&#8212;&#8203;in the event that the library is rejected&#8212;&#8203;that
the library be removed from the project VCS, or that some part be removed. Most often,
the library is approved and the CQ is marked as such.</simpara>
<simpara>Be advised that this process may take a while. The actual amount of time that it takes
to process a CQ depends on numerous factors including the size of the queue, and the
nature and size of the contribution.</simpara>
</section>
</section>
<section xml:id="ip-iplog">
<title>IP Logs</title>
<simpara>An IP Log is a record of the intellectual property contributions to a project.
This includes such as a list of all committers, past and present, that have
worked on the code and (especially) those who have made contributions to
the current code base.</simpara>
<simpara>The IP Log is a big part of the official <link linkend="release">release cycle</link>. You are required to
submit your project&#8217;s IP Log prior to scheduling a release, or restructuring
review. We encourage you to keep your IP log current rather than rushing at the
end. The IP Log includes important information about your project that lets
adopters know where all the code comes from, who owns the copyrights, and so
forth.</simpara>
<simpara>Specifically, the log tracks:</simpara>
<itemizedlist>
<listitem>
<simpara>Licenses;</simpara>
</listitem>
<listitem>
<simpara>Past and present committers;</simpara>
</listitem>
<listitem>
<simpara>Third-party libraries; and</simpara>
</listitem>
<listitem>
<simpara>Contributions from outside the project (i.e. non-committers)</simpara>
</listitem>
</itemizedlist>
<section xml:id="ip-iplog-generator">
<title>IP Log Generator</title>
<simpara>The Automated IP Log Tool automatically generates an IP Log using information
that is available to the Eclipse Foundation. The list of committers, for
example is generated using information provided by the Dash project which itself
pulls information out of source code repositories.</simpara>
<simpara>The IP Log generator pulls information from multiple location to assemble the log:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/ip-log-generator.png"/>
</imageobject>
<textobject><phrase>ip log generator</phrase></textobject>
</mediaobject>
</informalfigure>
<itemizedlist>
<listitem>
<simpara>Third-party libraries used by the project come from <emphasis>IPZilla</emphasis>;</simpara>
</listitem>
<listitem>
<simpara>The <emphasis>Dash</emphasis> process scans the project source code repositories to assess committer activity;</simpara>
</listitem>
<listitem>
<simpara><emphasis>Dash</emphasis> also scans Git repositories for contributions;</simpara>
<itemizedlist>
<listitem>
<simpara>If you follow the guidelines for handling Git contributions, contributions received via
Git in any branch will automatically appear in the log</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>Contributions received as patches in <emphasis>Bugzilla</emphasis> that are marked <literal>iplog+</literal>
will automatically appear in the log; and</simpara>
</listitem>
<listitem>
<simpara>License information is obtained from the <emphasis>Foundation</emphasis> database</simpara>
</listitem>
</itemizedlist>
<simpara>To fully leverage the value of the Automated IP Log Tool, you need to:</simpara>
<itemizedlist>
<listitem>
<simpara>Keep your project metadata up-to-date;</simpara>
</listitem>
<listitem>
<simpara>Follow the guidelines for handling Git contributions;</simpara>
</listitem>
<listitem>
<simpara>Mark IP Contributions in Bugzilla; and</simpara>
</listitem>
<listitem>
<simpara>Create <link linkend="ip-cq">contribution questionnaires</link> (CQs) where appropriate</simpara>
</listitem>
</itemizedlist>
<warning>
<simpara>Contributions should be recorded in <emphasis>one of</emphasis> Git or Bugzilla, not both.
Setting the <emphasis>Author</emphasis> credentials on Git commits is the preferred mechanism.
The IP Log generator is not smart enough to detect duplicate entries.</simpara>
</warning>
<simpara>Your project&#8217;s metadata is used to determine the identities of the source code
repositories that Dash needs to scan to find out committer information. Specifically,
you need to specify, in the <emphasis>Source Repositories</emphasis> section, a list of paths to source code
repository locations.</simpara>
<simpara>The Automated IP Log tool populates the <emphasis>Contributors</emphasis> section with information gathered
from Git and Bugzilla. This section lists contributions from non-committers (this is
time-sensitive, so contributions made by current committers before they became
committers will also be included). Only non-committer contributions are recorded in
the generated log.</simpara>
<simpara><link linkend="resources-commit">Git commits</link> contributed by non-committers are identified by
the author credentials on the commit record; the <emphasis>Author</emphasis> field must be set to the identity
of the actual author of the commit.</simpara>
<simpara>Alternatively, Bugzilla attachments can be marked with the <literal>iplog+</literal> flag.
This flag setting indicates that the person who attached  the bug is the contributor.
To comply with the website terms of use, the person who attaches
the contribution <emphasis role="strong">must</emphasis> be the person who has permission to make it available.
You should ensure that this is the case before including the code in your project&#8217;s
repository and flagging the entry.</simpara>
<simpara>You can also flag an entire Bugzilla entry with <literal>iplog+</literal>. Doing so,
however, indicates to the Automated IP Log tool that every single comment made by a non-committer
in the bug report represents a potential contribution. For your own sanity, it&#8217;s a good practice
to ask contributors to provide and attach patches that can be individually marked. Marking an
entire bug represents an ongoing maintenance issue as new comments added to the bug from
non-committers will show up in the generated log.</simpara>
<simpara>That contributions flagged in Bugzilla will only appear in the IP Log if the bug is marked
<literal>FIXED</literal> or <literal>CLOSED</literal>.</simpara>
<simpara>The Third-Party Software section of the log is populated from IPZilla. The IP Team
will mark your contributions in such a way that they will appear in
the log. If third party software is not appearing properly, contact the
<link xlink:href="mailto:emo-ip-team@eclipse.org">EMO IP Team</link> to make corrections.</simpara>
</section>
</section>
<section xml:id="ip-faq">
<title>Frequently Asked Questions</title>
<qandaset>
<qandaentry>
<question>
<simpara>Do we really need to do this? </simpara>
</question>
<answer>
<simpara>Yes.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What do you do with the IP Log? </simpara>
</question>
<answer>
<simpara>IP Log reviews occur in two stages. In the first stage, the EMO performs
a technical assessment to make sure that the artifacts produced by the
project are properly accounted for in the IP log. You may be asked to
assist with the resolution of any discrepancies found during this assessment.
In the second stage, the IP Team reviews the log to ensure that
it matches their records. The IP log review concludes with approval by the IP Team.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>When should I submit the IP Log for review? </simpara>
</question>
<answer>
<simpara>The IP Log should be submitted for review by the IP Team two weeks before the planned
end date for a release review or (if code moves are involved) a restructuring review.
Note that the date of your review may be different from the date of the actual release.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Are there other reasons to submit the IP Log for review? </simpara>
</question>
<answer>
<simpara>Generally no. If the IP Team requires an IP Log review outside of the context of
a release or restructuring review, they&#8217;ll ask for it. It is not generally necessary
to submit an IP Log for review outside of the context of a review.
It is, however, good practice to do your own review of the generated
IP Log periodically to make    sure that it accurately reflects the state of the project.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How do I fix problems with the generated IP Log? </simpara>
</question>
<answer>
<simpara>The IP Log is generated based on data from Eclipse Foundation servers. If the log
is being generated incorrectly, then the underlying data needs to be fixed. If
you spot a problem, send a note to <link xlink:href="mailto:emo@eclipse.org">emo@eclipse.org</link>.</simpara>
</answer>
</qandaentry>
</qandaset>
</section>
</chapter>
<chapter xml:id="release">
<title>Releases</title>
<simpara>Releases are formal for PolarSys projects. They start with planning,
and end with a community review. You can capture as many future releases as you&#8217;d like. It&#8217;s
common practice to specify releases three or six months into the future.</simpara>
<simpara>Releases are broadly categorized as:</simpara>
<itemizedlist>
<listitem>
<simpara><emphasis>Major</emphasis> releases include API changes (potential for downstream breakage);</simpara>
</listitem>
<listitem>
<simpara><emphasis>Minor</emphasis> releases add new functionality, but are API compatible with previous versions; and</simpara>
</listitem>
<listitem>
<simpara><emphasis>Service</emphasis> releases include bug fixes only and include no significant new functionality.</simpara>
</listitem>
</itemizedlist>
<simpara>For all major and minor releases, you must engage in a <emphasis>release review</emphasis>.
Release reviews are not required for bug-fix/service releases.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/release-cycle.png"/>
</imageobject>
<textobject><phrase>The release cycle</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara xml:id="releases-plan">A project plan is <emphasis>required</emphasis> for each major and minor project release.
The plan should lay out in broad terms what the goals are for the
release. As plans are a valuable means
for the community to get involved with your project, the plan should be
created at the beginning of the release cycle. By establishing the plan
early, you give prospective contributors help in determining how they
can most usefully contribute, and adopters can prepare their own
development schedule and themes. Plans can change during the release
cycle.</simpara>
<simpara>Use the <link linkend="pmi">Project Management Interface</link> to create a new release
record. At the start of the release cycle, your plan should minimally
include a release number, date, and short description. Think of the
description as an "elevator pitch": how would you describe the release
in a fifteen second elevator ride? All aspects of a plan can change
during the release cycle (including the date). If you do change the plan,
make sure that the change is communicated via your project&#8217;s <emphasis>dev</emphasis> list
and other project channels.</simpara>
<simpara>The <emphasis>Plan</emphasis> tab in the release record contains numerous fields for capturing
plan information. The amount of information that you should capture
for a release plan varies by top-level project, so consult with your
Project Management Committee (PMC) for advice.</simpara>
<simpara>Producing regular builds is an important part of the release cycle.
Builds are an important means of engaging with the community: adopters can
help you test your code and test their own so that they can be ready for
the eventual release. Plan to produce at least one <emphasis>milestone</emphasis> build (more
are better, depending on the length of your release cycle), and capture
the planned date for that milestone in the release record. It is also
common practice to generate nightly and weekly integration builds. Ensure that
your project&#8217;s downloads page provides the information required for the
community to obtain your builds.</simpara>
<simpara>All of your project&#8217;s <link linkend="ip">intellectual property</link> contributions
must be approved by the IP Team before you can release
(this includes third-party libraries and contributions of code to be
maintained by the project).</simpara>
<section xml:id="release-review">
<title>Release Review</title>
<simpara>A <emphasis>release review</emphasis> is a formal announcement of your release to the
community and a request for feedback. In practical terms, experience
has shown that those individuals and organizations who are interested
in your project follow development throughout the release cycle and so
are have likely already provided feedback during the development
cycle (i.e. they are unlikely to provide feedback during the review
period). With this in mind, the review generally serves as a means for
a project to engage in a retrospective of the progress made during the
release, discover areas of potential improvement, demonstrate that the
project is operating in an open and transparent manner, and ensure that
the development process and intellectual due diligence processes have
been followed.</simpara>
<simpara>Release reviews run for a week and always conclude on a Wednesday.</simpara>
<note>
<simpara>We schedule reviews to conclude on the <emphasis>first and
third Wednesdays of the month</emphasis>. Your release date does not have to
coincide with the review date (you can set the release date as
necessary). The review must, however, conclude successfully before you
can make the release official.</simpara>
</note>
<simpara>A <emphasis>release review</emphasis> requires review documentation and an intellectual
property (IP) log check. The review process must be initiated at least
two weeks in advance of the anticipated <emphasis>review</emphasis> date.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/release-review.png"/>
</imageobject>
<textobject><phrase>Release review work flow</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>Prepare the review documentation well in advance of the start of the
review period. The release record which contains your project plan
also includes a <emphasis>Review</emphasis> tab with appropriate fields for a review.
As with the plan fields, all of the review fields are optional and
the level of detail you need to provide varies by top-level project.
You can assemble review information during the release cycle (there&#8217;s
no need to wait until the end)</simpara>
<simpara>The review materials must be approved by the PMC; send an email to
the PMC&#8217;s mailing list asking for approval. The PMC will respond with
feedback or a simple "+1" indicating approval.</simpara>
<note>
<simpara>Click the handy <emphasis>Send Email to the PMC</emphasis> link under <emphasis>Committer Tools</emphasis>
on the release record page to connect with the PMC.</simpara>
</note>
<simpara>Submit the IP Log for review by the IP Team. The IP Team must approve
the IP Log before we can schedule the review, so submitting this early
is important. The <link linkend="ip-iplog-generator">IP Log generator</link> automatically
collects information based on the information that the project team has
provided to the IP Team through <link linkend="ip-cq">contribution questionnaires</link>
in IPZilla, commits in the project&#8217;s source code repository, and
other information in our databases. Carefully review the IP Log before
submitting to the IP Team for their review.</simpara>
<note>
<simpara>Click the handy <emphasis>Generate IP Log</emphasis> link under <emphasis>Committer Tools</emphasis>
on the release record page to open the IP Log generator.</simpara>
</note>
<simpara>The information used to generate an IP Log should always be up-to-date
(don&#8217;t wait until the end of the release cycle to make it right).</simpara>
<simpara>At any point in this process, you can request that the review be
initiated by clicking the <emphasis>Schedule a review for this release</emphasis> link
that appears at the top of the release record page. This will invite you
to select a review date. You must then follow up with the EMO to approve
the review.</simpara>
<note>
<simpara>The EMO will likely notice that you&#8217;ve created the release record,
connected with your PMC, and submitted an IP Log for review by the IP
team and will take steps to initiate the actual review. However, since
there is a great deal of variability in this process, send an email to
<link xlink:href="mailto:emo@eclipse.org">emo@eclipse.org</link> stating your intent to release.</simpara>
</note>
<simpara>The EMO will conclude the review on the scheduled end date and advise the
project team of the outcome.</simpara>
</section>
<section xml:id="release-graduation">
<title>Graduation Review</title>
<simpara>The purpose of a <emphasis>graduation review</emphasis> is to confirm that the project has
a working and demonstrable code base of sufficiently high quality
active and sufficiently diverse communities; has adopters, developers, and users
operating fully in the open following the <link xlink:href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</link>; and
is a credit to PolarSys and is functioning well within the larger PolarSys community</simpara>
<simpara>Graduation reviews are generally combined with a <link linkend="release-review"><emphasis>release review</emphasis></link>
(typically, but not necessarily the <emphasis>1.0</emphasis> release).
Upon successful completion of a graduation review, a project will leave the
incubation phase and be designated as a <emphasis>mature</emphasis> project.</simpara>
<simpara>For a graduation review, release review documentation must be augmented to
include demonstration of:</simpara>
<itemizedlist>
<listitem>
<simpara>solid working code with stable APIs;</simpara>
</listitem>
<listitem>
<simpara>an established and growing community around the project;</simpara>
</listitem>
<listitem>
<simpara>diverse multi-organization committer/contributor/developer activity; and</simpara>
</listitem>
<listitem>
<simpara>operation in the open using open source rules of engagement.</simpara>
</listitem>
</itemizedlist>
<simpara>The graduation review documentation should demonstrate that members have
learned the ropes and logistics of being a PolarSys project. That is,
the project "gets the PolarSys way".</simpara>
</section>
<section xml:id="release-faq">
<title>Frequently Asked Questions</title>
<qandaset>
<qandaentry>
<question>
<simpara>Can a release review fail? </simpara>
</question>
<answer>
<simpara>Technically, yes. A release review can fail. In our history, however, this
occurrs very rarely. We set up release reviews to succeed.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Do we really need to do this? </simpara>
</question>
<answer>
<simpara>Yes.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How often should we do releases? </simpara>
</question>
<answer>
<simpara>This depends very much on the nature of your project and the expectations
of your community and stake holders. If you&#8217;re not sure, connect with your
mentors and top-level project for guidance.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How much effort should we put into this? </simpara>
</question>
<answer>
<simpara>The amount of effort varies based on the nature of the team, and
expectations of the community and stake holders. Generally, though, a project
team shouldn&#8217;t spend more than a couple of hours working directly on the
formal aspects of the release review.
If the amount of effort seems too onerous, you may be trying too hard.
Connect with your project mentors, top-level project&#8217;s PMC, or the
<link xlink:href="mailto:emo@eclipse.org">EMO</link> for guidance.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How do I submit the IP Log for review? </simpara>
</question>
<answer>
<simpara>Click the <emphasis>Submit</emphasis> button on the <link linkend="ip-iplog-generator">IP Log generator</link>.
You need to be logged in as project committer to have access to this button.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Can I accept contributions after I submit the IP Log for review? </simpara>
</question>
<answer>
<simpara>The short answer is <emphasis>yes</emphasis>. Please do accept contributions.
If you require a new contribution questionnaire (for either a third
party library or code contribution) after submitting the IP Log for
review, please ask the <link xlink:href="mailto:emo-ip-team@eclipse.org">IP Team</link> if
they want you to resubmit the IP Log.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How do I obtain PMC approval? </simpara>
</question>
<answer>
<simpara>Send the the PMC a note via the top-level project&#8217;s <emphasis>PMC</emphasis> mailing list
with a link to the release record. Note that the release record page
has a handy link labeled <emphasis>Send Email the PMC</emphasis> under <emphasis>Committer Tools</emphasis>.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>I need to do a release now. Can you fast-track the review? </simpara>
</question>
<answer>
<simpara>While we do try to be as accommodating as possible, the answer is no.
We have a well-defined process with predictable dates. Please plan
accordingly.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>Can a project in the incubation phase do releases? </simpara>
</question>
<answer>
<simpara>Yes. In fact, we encourage projects to do at least one release while
in incubation phase.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>What restrictions are placed on version names for incubating projects? </simpara>
</question>
<answer>
<simpara>Projects in the incubation phase generally use version numbers that
are less than 1.0. This is, however, a convention not a rule. If it makes sense
for you community and adopters to use higher numbers, then do so.
If you&#8217;re not sure, ask your top-level project PMC for advice.</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How do I name/number milestone builds? </simpara>
</question>
<answer>
<simpara>Milestone builds should contain the name/number of the release suffixed
with "Mn" (e.g. the second milestone for EGit 3.2 may have a file
named "egit-3.2M2"). Projects in the incubation phase may produce
milestone builds for their graduation release, e.g "myProject-1.0M2".</simpara>
</answer>
</qandaentry>
<qandaentry>
<question>
<simpara>How can I get help? </simpara>
</question>
<answer>
<simpara>Contact your mentors (for projects in the incubation phase), top-level
project PMC, or the <link xlink:href="mailto:emo@eclipse.org">EMO</link>.</simpara>
</answer>
</qandaentry>
</qandaset>
</section>
</chapter>
<chapter xml:id="pmi">
<title>Project Management Infrastructure (PMI)</title>
<simpara>The PolarSys Project Management Infrastructure (PMI) consolidates
project management activities into a single consistent location and experience.</simpara>
<simpara>Project Management Infrastructure themes:</simpara>
<simpara><emphasis>Improved consistency.</emphasis> Configuration/data-driven project web presence,
direct linkage between releases, reviews, and plans. Information&#8212;&#8203;including
basic project metadata, project plans, and release review information&#8212;&#8203;is
captured and retained in a consistent (and easily leveraged) data-based
format (rather than in multiple documents in arbitrary formats).</simpara>
<simpara><emphasis>All-in-one-place.</emphasis> 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.</simpara>
<simpara><emphasis>Get started faster.</emphasis> 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.</simpara>
<section xml:id="pmi-metadata">
<title>Project Metadata?</title>
<simpara>Project committers and project leads are responsible for maintaining
their project&#8217;s metadata. This information is an important part of being
an Eclipse project.</simpara>
<simpara>Project metadata is:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>Relatively static structural information such as the project
description and scope, the names of the project&#8217;s mailing lists and
newsgroups, the bugzilla products, source code repositories, etc.</simpara>
</listitem>
<listitem>
<simpara>Historical information such as previous release downloads, release
review slides and IP logs, etc.</simpara>
</listitem>
<listitem>
<simpara>Status and future looking information such as the project and
milestone plans, the features scheduled for the current release, release
dates, etc.</simpara>
</listitem>
</orderedlist>
<simpara>PMC members, and the Eclipse Foundation staff also have the ability to
make changes on behalf of a project.</simpara>
</section>
<section xml:id="pmi-viewing">
<title>Viewing</title>
<simpara>The complete listing of all current
<link xlink:href="http://www.polarsys.org/list-of-projects">PolarSys projects</link> 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.</simpara>
</section>
<section xml:id="pmi-commands-and-tools">
<title>Commands and Tools</title>
<simpara>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.</simpara>
</section>
<section xml:id="pmi-editing">
<title>Editing Project Metadata</title>
<simpara>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).</simpara>
<simpara>Some of the fields are described below.</simpara>
<section xml:id="pmi-description-and-scope">
<title>Description and Scope</title>
<simpara>The <emphasis>description</emphasis> 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.</simpara>
<simpara>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 <emphasis>Teaser Break</emphasis> into the content.</simpara>
<note>
<simpara>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 <emphasis>weird</emphasis>.</simpara>
</note>
<simpara>The <emphasis>scope</emphasis> is intended for a more select audience; generally speaking the
scope should be taken directly from the project&#8217;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.</simpara>
</section>
<section xml:id="pmi-downloads">
<title>Downloads</title>
<simpara>You can provide download information for your project in the "Downloads"
section.</simpara>
<simpara>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.</simpara>
<simpara>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.</simpara>
</section>
<section xml:id="source-repositories">
<title>Source Repositories</title>
<simpara>The project can specify zero or more <emphasis role="strong">source repositories</emphasis>. These are
displayed in the "Contribute to this Project" section.</simpara>
<simpara>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.</simpara>
<simpara>Repositories should be specified using the file system path, e.g.
<emphasis>/gitroot/egit/egit.git</emphasis>. The name that is displayed for the repository
is extracted from the last segment of the URL.</simpara>
<simpara>If a description file exists in the Git repository, the contents are
automatically displayed under the repository name.</simpara>
<note>
<simpara>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.</simpara>
</note>
<simpara>You can use wildcards to match multiple repositories, e.g.
<emphasis>/gitroot/virgo/*</emphasis>. Note that wildcards only work for repositories that
exist on PolarSys infrastructure (they do not work for GitHub-based
repositories, for example).</simpara>
<simpara>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.</simpara>
<simpara>A <emphasis role="strong">Contribution Message</emphasis> 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.</simpara>
</section>
<section xml:id="pmi-company-logos">
<title>Company Logos</title>
<simpara>Company logos sometimes appear on project pages under the following
conditions"</simpara>
<itemizedlist>
<listitem>
<simpara>The company must be a <link xlink:href="http://eclipse.org/membership/">member</link> of the
Eclipse Foundation;</simpara>
</listitem>
<listitem>
<simpara>The company needs to have their logo uploaded to the Portal;</simpara>
</listitem>
<listitem>
<simpara>At least one committer has to be listed as an employee of the company
in question;</simpara>
</listitem>
<listitem>
<simpara>The committer must be on this project; and</simpara>
</listitem>
<listitem>
<simpara>The committer must be active (must have made at least one commit in
the last three months)</simpara>
</listitem>
</itemizedlist>
<simpara>If all of those conditions are met and the logo is still not showing up,
then it&#8217;s possible that the project meta-data doesn&#8217;t have the correct
source code repository information specified.</simpara>
</section>
<section xml:id="pmi-build-technology">
<title>Build Technology</title>
<simpara>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.</simpara>
</section>
<section xml:id="pmi-technology-types">
<title>Technology Types</title>
<simpara>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.</simpara>
<simpara>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).</simpara>
</section>
</section>
<section xml:id="pmi-releases">
<title>Releases and Reviews</title>
<simpara>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 <emphasis>review</emphasis> 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.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="images/ProjectsReleasesReviews.png"/>
</imageobject>
<textobject><phrase>Releases and Reviews</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>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).</simpara>
<simpara>Each <link linkend="release">release</link> 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.</simpara>
<note>
<simpara>_Create a single record for each release. <emphasis role="strong">Do not create release records
for milestones.</emphasis> Enter milestone information in the <emphasis>Plan</emphasis> information
for your release.</simpara>
</note>
<simpara>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.</simpara>
<section xml:id="pmi-release-description">
<title>Description</title>
<simpara>Describe the release in the <emphasis>Description</emphasis> 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.</simpara>
</section>
<section xml:id="pmi-release-issues">
<title>Issues</title>
<simpara>The release record will automatically generate a list of targeted bugs.</simpara>
<simpara>To populate this list:</simpara>
<itemizedlist>
<listitem>
<simpara>Ensure that the Bugzilla Product is set the to correct value in the
project metadata;</simpara>
</listitem>
<listitem>
<simpara>Set the "target milestones" in Bugzilla need to match the name of your
release.</simpara>
</listitem>
</itemizedlist>
<note>
<simpara>The matching algorithm tries to be as forgiving as possible, a release
  named "3.5", "3.5.0", or "3.5 (Luna)" will&#8212;&#8203;for example&#8212;&#8203;match target
  milestones named "3.5" ,"3.5M1", "3.5 M2", "3.5.0M3", etc., but will
  not match "3.5.1".</simpara>
</note>
<simpara>The bugs for all projects participating in the release will be included.
Bugs are grouped by Bugzilla product and component.</simpara>
</section>
<section xml:id="pmi-release-plan">
<title>Plan</title>
<simpara><link linkend="releases-plan">Project plan</link> information belongs in the <emphasis>Plan</emphasis> section. This
information <emphasis role="strong">should</emphasis> 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).</simpara>
</section>
<section xml:id="pmi-release-milestones">
<title>Milestones</title>
<simpara>Enter the name, date, and optional description for each milestone
expected with the release.</simpara>
<simpara>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.</simpara>
</section>
<section xml:id="pmi-review">
<title>Review</title>
<simpara>The release has a <link linkend="release-review"><emphasis>Review</emphasis></link> 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.</simpara>
<simpara>Each section on the review page includes a little help to describe the
sort of information that you should provide.</simpara>
<simpara>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.</simpara>
<simpara>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.</simpara>
<simpara>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.</simpara>
<simpara>You can edit the review document, but there&#8217;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. <emphasis>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.</emphasis></simpara>
<simpara>When the review is displayed, it automatically includes the <emphasis>review</emphasis>
information from the release record; it shows the review-specific
information at the top of the page, and includes the <emphasis>review</emphasis>
information from the release as the rest of the page contents.</simpara>
<simpara>This can make things a bit confusing when you want to make changes to
the metadata for a review record. Just remember that the <emphasis>review</emphasis>
information for a release is stored in the release record.</simpara>
</section>
</section>
</chapter>
<chapter xml:id="glossary">
<title>Glossary</title>
<glossentry>
<glossterm>Architecture Council </glossterm>
<glossdef>
<simpara>The Eclipse Architecture Council (AC) serves the community by identifying and
tackling any issues that hinder Eclipse&#8217;s continued technological success and
innovation, widespread adoption, and future growth. This involves technical
architecture as well as open source processes and social aspects. Comprising
the finest technical leaders from all community stake holders, it is the council&#8217;s
goal to keep the projects successful and healthy, the processes simple and smooth,
and the communities vibrant and cohesive.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Architecture Council Mentor </glossterm>
<glossdef>
<simpara>The Eclipse Architecture Council (AC) is a body of battle-hardened Eclipse committers.
All new projects are required to have a minimum of two mentors taken from the ranks
of the AC. Your project mentors will help you find answers to any questions you may
have about the Eclipse Development Process and life-in-general within the Eclipse
community. If your mentor doesn&#8217;t have an answer to your question, they can draw
on the wisdom of the full AC and the EMO.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Board of Directors </glossterm>
<glossdef>
<simpara>The business and technical affairs of the Eclipse
Foundation are managed by or under the direction of the Board of Directors
(or more simply, "The Board").</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Committer </glossterm>
<glossdef>
<simpara>A committer is a software developer who has the necessary rights to write code
into the project&#8217;s source code repository. Committers are responsible for ensuring
that all code that gets written into the project&#8217;s source code repository is of
sufficient quality. Further, they must ensure that all code written to an
PolarSys source code repository is clean from an intellectual property point
of view. This is discussed with more detail below.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Community </glossterm>
<glossdef>
<simpara>Community is a nebulous sort of term. Community is the group of individuals and
organizations that gather around your project. In the case of some projects, the community
is enormous. Other projects have smaller communities. Developing a
community is a very important part of being a PolarSys project as it is from the
community that you get feedback, contributions, fresh ideas, and ultimately new
committers to help you implement your shared vision.
The <emphasis>PolarSys Community</emphasis> is formed from the union of the communities that grow
around individual projects.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Contribution Questionnaire </glossterm>
<glossdef>
<simpara>Prior to committing a significant contribution of content from a non-committer
to a PolarSys project, the committer must fill out a <link linkend="ip-cq">contribution questionnaire</link> (CQ) and
submit it to the IP Team for approval. In addition to the
EMO, the relevant PMC must also provide a technical review and approval of the contribution.
In general, ongoing development by project committers does not require EMO or PMC approval.
When in doubt, consult the <link xlink:href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">Eclipse IP Due Diligence Process</link>.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Contributor </glossterm>
<glossdef>
<simpara>A contributor is anybody who makes contributions to the project. Contributions
generally take the form of code patches, but may take other forms like comments
on issues, additions to the documentation, answers to questions in forums, and
more.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Dash Process </glossterm>
<glossdef>
<simpara>The Dash Process, or simply <emphasis>Dash</emphasis>, is a collection of scripts and processes that
harvest project data for dissemination in charts, <link linkend="ip-iplog">IP Logs</link>, and more.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Dev-list </glossterm>
<glossdef>
<simpara>Every project has a <emphasis>development list</emphasis> or <emphasis>dev-list</emphasis>. All project
committers must subscribe to the list. The dev-list should be the primary means
of communication between project committers and is the means throuh which the
Eclipse Foundation&#8217;s automated systems communicate with the project.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Ecosystem </glossterm>
<glossdef>
<simpara>A commercial ecosystem is a system in which companies, organizations, and individuals
all work together for mutual benefit. There already exists a vast ecosystem of companies
that base significant parts of their business on PolarSys technology. This takes the
form of including PolarSys code in products, providing support, and other services.
You become part of an eco-system by filling the needs of commercial interests, being
open and transparent, and being responsive to feedback.
Ultimately, being part of a commercial ecosystem is a great way to ensure the
longevity of your project: companies that build their business around your project
are very motivated to contribute to your project.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Eclipse </glossterm>
<glossdef>
<simpara>Now this is a tough one. For most people in the broader community, "Eclipse" refers to a
Java IDE based on the JDT project and assembled by the Eclipse Packaging Project. However,
the term "Eclipse" is also used to refer to the Eclipse Foundation, the eclipse.org website,
the community, the eco-system, and&#8212;&#8203;of course&#8212;&#8203;The Eclipse Project (which is just one of
the top-level projects hosted by the Eclipse Foundation). Confusing? Yes.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>EMO </glossterm>
<glossdef>
<simpara>The Eclipse Management Organization (EMO) consists of the Eclipse Foundation staff, and the Architecture and Planning
Councils. The EMO is responsible for providing services to the projects, facilitating
project reviews, resolving issues, and more. The EMO is the maintainer of the Eclipse
Development Process. The best method of contact with the EMO is by email (<link xlink:href="mailto:emo@eclipse.org">emo@eclipse.org</link>).
If you have a question that cannot be answered by project lead, mentor, or PMC, ask the EMO.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>EMO Executive Director </glossterm>
<glossdef>
<simpara>The EMO Executive Director (EMO/ED) is the head-honcho at the Eclipse Foundation. He is
ultimately responsible for all the goings-on at the Eclipse Foundation.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>EMO IP Team </glossterm>
<glossdef>
<simpara>The EMO Intellectual Property Team (commonly referred to
as the <emphasis>IP Team</emphasis>) is responsible for implementing the intellectual
property policy of the Eclipse Foundation.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>EMO Records </glossterm>
<glossdef>
<simpara>The EMO Records Team (commonly referred to as <emphasis>EMO Records</emphasis>) is
responsible for managing committer paperwork and other records
on behalf of the Eclipse Foundation. Contact the EMO Records team via email
(<link xlink:href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</link>).</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Incubation Phase </glossterm>
<glossdef>
<simpara>The purpose of the incubation phase is to establish a fully-functioning open-source project.
In this context, incubation is about developing the process, the community, and the technology.
Incubation is a phase rather than a place: new projects may be incubated under any existing project.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>IP Due Diligence Process </glossterm>
<glossdef>
<simpara>The <link xlink:href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">Intellectual Property Due Diligence Process</link> defines the process by which
intellectual property is added to a project. All PolarSys committers must be familiar
with this process.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>IP Log </glossterm>
<glossdef>
<simpara>An <link linkend="ip-iplog">IP Log</link> is a record of the intellectual property (IP) contributions to a project.
This includes such as a list of all committers, past and present, that have worked on the
code and (especially) those who have made contributions to the current code base.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Member Company </glossterm>
<glossdef>
<simpara>The Eclipse Foundation and Eclipse community is supported by our member organizations.
Through this support, the Eclipse Foundation provides the open source community
with IT, Intellectual Property, Mentors and Marketing services.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Parallel IP </glossterm>
<glossdef>
<simpara>The <link linkend="ip-parallel-ip">Parallel IP Process</link> allows a PolarSys projects to make use of
project code contributions and third-party libraries before they
are fully approved by the IP Team.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Planning Council </glossterm>
<glossdef>
<simpara>The Planning Council is responsible for cross-project planning, architectural issues,
user interface conflicts, and all other coordination and integration issues. The Planning
Council discharges its responsibility via collaborative evaluation, prioritization, and compromise.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Project</glossterm>
<glossdef>
<simpara>Projects are where the real work happens. Each project has code, committers,
and resources including a web site, source code repositories, space on the build
and download server, etc. Projects may act as a parent for one or more child
projects. Each child project has its own identity, committers, and resource.
Projects may, but do not necessarily, have a dedicated web site. Projects are sometimes referred
to as <emphasis>subprojects</emphasis> or as <emphasis>components</emphasis>.  The Eclipse Development Process, however,
treats the terms project, subproject, and component as equivalent.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Project Lead </glossterm>
<glossdef>
<simpara>The project lead is more of a position of responsibility than one of power. The
project lead is immediately responsible for the overall well-being of the project.
They own and manage the project&#8217;s development process, coordinate development,
facilitate discussion among project committers, ensure that the Eclipse IP
policy is being observed by the project and more. If you have questions about
your project, the <link xlink:href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</link>, or anything else, ask
your project lead.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>PMC </glossterm>
<glossdef>
<simpara>Each top-level project is governed by a Project Management Committee (PMC). The
PMC has one or more leads along with several members. The PMC has numerous
responsibilities, including the ultimate approval of committer elections, and
approval of intellectual property contributions. Effectively, the PMC provides
oversight for each of the projects that are part of the top-level project.
If you have a question that your project lead cannot
answer, ask the PMC.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>PMI </glossterm>
<glossdef>
<simpara>The Project Management Interface (PMI) is the system that tracks the state
and progress of PolarSys projects. Project committers can modify the the
information represented in the PMI, including the project description, and
information about project releases. Automated systems use this information
to, for example, generate dashboard and chart information for the project,
intellectual property logs, etc.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Top-Level Project </glossterm>
<glossdef>
<simpara>A top-level project (sometimes referred to as a <emphasis>TLP</emphasis>) is effectively a
container for projects that do the real work.
A top-level project does not generally contain code; rather, a top-level project contains
other projects. Each top-level project defines a charter that, among other
things defines a scope for the types of projects that it contains. Top-level
projects are managed by a Project Management Committee.</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Webmaster </glossterm>
<glossdef>
<simpara>The Webmaster team is responsible for maintaining the IT infrastructure
of the Eclipse Foundation and the PolarSys forge. You can contact the
Webmaster team directly via email (<link xlink:href="mailto:webmaster@eclipse.org">webmaster@eclipse.org</link>).</simpara>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Working Group </glossterm>
<glossdef>
<simpara>Eclipse <link xlink:href="https://www.eclipse.org/org/workinggroups">Working Groups</link> provide
a vendor-neutral governance structure that allow organizations to freely
collaborate on new technology development.</simpara>
</glossdef>
</glossentry>
</chapter>
<chapter xml:id="contact">
<title>Getting Help</title>
<simpara>If you have any questions, or are unsure of your responsibilities as a
project lead or committer, please contact your project mentors or
<link xlink:href="mailto:emo@eclipse.org">EMO</link>.</simpara>
</chapter>
</book>