| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 1.5.2"> |
| <title>PolarSys Project Handbook</title> |
| <link rel="stylesheet" href="./resources/github.css"> |
| </head> |
| <body class="book"> |
| <div id="header"> |
| <h1>PolarSys Project Handbook</h1> |
| <div id="toc" class="toc"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#preamble">Overview</a> |
| <ul class="sectlevel2"> |
| <li><a href="#preamble-principles">Principles</a></li> |
| </ul> |
| </li> |
| <li><a href="#starting">Starting an Open Source Project at PolarSys</a> |
| <ul class="sectlevel2"> |
| <li><a href="#starting-after-provisioning">After Provisioning</a></li> |
| <li><a href="#starting-project-phases">Project Phases</a></li> |
| <li><a href="#starting-faq">Frequently Asked Questions</a></li> |
| </ul> |
| </li> |
| <li><a href="#project-resources-and-services">Project Resources and Services</a> |
| <ul class="sectlevel2"> |
| <li><a href="#resources-source">Source Code Management</a></li> |
| <li><a href="#resources-issues">Issue Trackers</a></li> |
| <li><a href="#resources-libraries">Third-party Libraries</a></li> |
| <li><a href="#resources-forums">Forums and Outbound Communication</a></li> |
| <li><a href="#resources-website">Project Websites</a></li> |
| <li><a href="#resources-builds">Builds</a></li> |
| <li><a href="#resources-downloads">Downloads</a></li> |
| </ul> |
| </li> |
| <li><a href="#paperwork">Committer Paperwork</a> |
| <ul class="sectlevel2"> |
| <li><a href="#paperwork-questionnaire">Committer Questionnaire</a></li> |
| <li><a href="#paperwork-documents">Documents</a></li> |
| <li><a href="#paperwork-existing">Existing Committer</a></li> |
| <li><a href="#paperwork-not-employed">Not Employed or Student</a></li> |
| <li><a href="#paperwork-faq">Frequently Asked Questions</a></li> |
| </ul> |
| </li> |
| <li><a href="#ip">Intellectual Property</a> |
| <ul class="sectlevel2"> |
| <li><a href="#ip-initial-contribution">Initial Contribution</a></li> |
| <li><a href="#ip-project-code">Project Code Contributions</a></li> |
| <li><a href="#ip-third-party">Third-Party Libraries</a></li> |
| <li><a href="#ip-ownership">Ownership</a></li> |
| <li><a href="#ip-copyright-headers">Copyright and License Headers</a></li> |
| <li><a href="#ip-licensing">Licensing</a></li> |
| <li><a href="#ip-cq">Contribution Questionnaires</a></li> |
| <li><a href="#ip-iplog">IP Logs</a></li> |
| <li><a href="#ip-faq">Frequently Asked Questions</a></li> |
| </ul> |
| </li> |
| <li><a href="#release">Releases</a> |
| <ul class="sectlevel2"> |
| <li><a href="#release-review">Release Review</a></li> |
| <li><a href="#release-graduation">Graduation Review</a></li> |
| <li><a href="#release-faq">Frequently Asked Questions</a></li> |
| </ul> |
| </li> |
| <li><a href="#pmi">Project Management Infrastructure (PMI)</a> |
| <ul class="sectlevel2"> |
| <li><a href="#pmi-metadata">Project Metadata?</a></li> |
| <li><a href="#pmi-viewing">Viewing</a></li> |
| <li><a href="#pmi-commands-and-tools">Commands and Tools</a></li> |
| <li><a href="#pmi-editing">Editing Project Metadata</a></li> |
| <li><a href="#pmi-releases">Releases and Reviews</a></li> |
| </ul> |
| </li> |
| <li><a href="#glossary">Glossary</a></li> |
| <li><a href="#contact">Getting Help</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Copyright © 2015 Eclipse Foundation, Inc., Made available under the Eclipse Public License v 1.0</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="preamble">Overview</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>While this document is focused on PolarSys, it makes several |
| "Eclipse" references, including the <em>Eclipse Foundation</em>, |
| <em>Eclipse Development Process</em>, and <em>Eclipse Management Organization</em>. |
| 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</a> (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.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="preamble-principles">Principles</h3> |
| <div class="paragraph"> |
| <p>Four basic principles lie at the heart of the Eclipse Development Process:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Transparency;</p> |
| </li> |
| <li> |
| <p>Openness;</p> |
| </li> |
| <li> |
| <p>Meritocracy; and</p> |
| </li> |
| <li> |
| <p>Vendor neutrality</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>We refer to the first three as the "open source rules of engagement".</p> |
| </div> |
| <div class="paragraph"> |
| <p>To operate with <strong>transparency</strong>, a project’s discussions, minutes, deliberations, |
| project plans, plans for new features, and other artifacts are open, public, |
| and easily accessible.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>Openness</strong> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>PolarSys is a <strong>meritocracy</strong>. 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 <a href="#elections">election</a>.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><strong>Vendor neutrality</strong> is similar to openness in that it’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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Quality and intellectual property cleanliness are also important principles.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>Quality</strong> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong><a href="#ip">Intellectual property</a></strong> (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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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’re |
| basing their products on is <strong>clean</strong>: 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.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="starting">Starting an Open Source Project at PolarSys</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>PolarSys open source projects start with a proposal that is made |
| available to the community for review. At the end of the <em>community |
| review</em> period, we engage in a <em>creation review</em>, and then |
| provision the project resources.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/project-creation.png" alt="An overview of the Project Creation Process"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Use the <a href="https://www.polarsys.org/node/add/project-proposal">web form</a> to create a new project proposal. |
| Instructions are provided on the form. All new proposals are created |
| in <em>draft</em> 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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>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 <em>community review</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When you feel that the proposal is ready, send a note to |
| the Eclipse Management Organization (EMO) at <a href="mailto:emo@eclipse.org">emo@eclipse.org</a> 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 <em>community review</em> period.</p> |
| </div> |
| <div class="paragraph"> |
| <p>At the beginning of the <em>community review</em> period, the EMO will |
| announce the proposal on several channels (the <a href="http://www.eclipse.org/projects/project_activity.php">Project |
| Activity News</a> page, Twitter, the |
| <a href="http://www.eclipse.org/forums/eclipse.proposals">Proposals Forum</a>, blog post, and an email note |
| to the Eclipse Foundation members and committers). The EMO will |
| also open an record in the Eclipse Foundation’s issue tracker—​an |
| instance of Bugzilla—​to track the progress of the proposal; |
| the proposal’s author and project leads will be copied on that record.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A proposal will be open for community review for a minimum of two |
| weeks.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation holds the <em>trademark</em> 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 |
| <a href="http://eclipse.org/legal/Trademark_Transfer_Agreement.pdf">Trademark Transfer Agreement</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The proposal must list two mentors from the Architecture Council. |
| Members of the Architecture Council have considerable experience with |
| Eclipse Foundation practices, and the <a href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</a>. |
| 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 |
| <a href="#release-graduation">graduates</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the project name trademark has been secured, mentors have been |
| identified, and the proposal contents are finalized, the EMO will schedule |
| a <em>creation review</em>. Reviews—​which run for a minimum of one week—​are |
| scheduled twice a month, generally concluding on the first and third |
| Wednesday of each month. The creation review may overlap with the |
| <em>community review</em> period.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Following the creation review, the EMO will initiate the provisioning process. |
| To gain committer status, some <a href="#paperwork">committer paperwork</a> 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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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’t send any paperwork in until after you receive |
| those instructions. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="sect2"> |
| <h3 id="starting-after-provisioning">After Provisioning</h3> |
| <div class="paragraph"> |
| <p>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’s <a href="#ip-initial-contribution"><em>initial contribution</em></a> and |
| list of third-party libraries for review by the IP team.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/post-creation.png" alt="Post creation activities"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Do not commit any code to your project’s source code repository until after |
| you receive approval for the IP Team. Once you’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 <a href="#release">releases</a>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="starting-project-phases">Project Phases</h3> |
| <div class="paragraph"> |
| <p>All new projects start in the <em>incubation phase</em> (a project in the |
| incubation phase is said to be <em>incubating</em>). The classification of |
| a project in the incubation phase is not a statement about the quality |
| of the project’s code; rather, incubation phase is more about the |
| project team’s progress in practicing the open and public processes |
| necessary to establish the three communities (developers, adopters, |
| and users) around the project.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/Egg-incubation.png" alt="The Incubation Logo"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In order to alert potential consumers of the incubating nature, |
| projects in the incubation phase must include <em>incubation branding</em>:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Display the incubation logo on their project web page (if they have one);</p> |
| </li> |
| <li> |
| <p>Displays the incubation logo on their project’s primary download page;</p> |
| </li> |
| <li> |
| <p>Include the word "incubation" in the filename of all downloadable |
| files (when technically feasible) for builds and milestones;</p> |
| </li> |
| <li> |
| <p>When technically feasible, include the word "incubation" in features |
| (e.g. about dialogs, feature lists, and installers).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>There are no incubation branding requirements for general |
| user interface elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For projects that produce OSGi artifacts, include the word |
| "incubation" in the <em>Bundle-Name</em>, feature names, and p2 repositories.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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’s <em>Bundle-SymbolicName</em>, or a |
| Java package name. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Incubating projects that correctly conform to the incubation branding |
| rules outlined above may take advantage of the <a href="#ip-parallel-ip">Parallel |
| IP Process</a>. They are encouraged to produce milestone builds, make |
| releases, and grow their community.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 <em>graduate</em> into |
| the <em>mature phase</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="starting-faq">Frequently Asked Questions</h3> |
| <div class="qlist qanda"> |
| <ol> |
| <li> |
| <p><em>How do I find Architecture Council mentors? </em></p> |
| <p>You don’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.</p> |
| </li> |
| <li> |
| <p><em>Can I change the proposal after it is posted? </em></p> |
| <p>Yes. The proposal can be changed any time before the start of the |
| start of the creation review.</p> |
| </li> |
| <li> |
| <p><em>When do I submit my code for review by the IP team? </em></p> |
| <p>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.</p> |
| </li> |
| <li> |
| <p><em>Does the new project have to use Git? </em></p> |
| <p>Yes. Git is the only source code management system that is currently |
| permitted for new projects.</p> |
| </li> |
| <li> |
| <p><em>Can I host my project code on GitHub? </em></p> |
| <p>New projects can make use of <a href="#resources-github">GitHub</a>. Official project repositories |
| must be moved under the <a href="https://github.com/polarsys">PolarSys Organization</a> at GitHub. |
| Official repositories are subject to the same intellectual |
| property due diligence rules and processes that all Eclipse project |
| repositories must follow.</p> |
| </li> |
| <li> |
| <p><em>How long should I let my project incubate? </em></p> |
| <p>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.</p> |
| </li> |
| <li> |
| <p><em>Does the mature project code that I’m bring to PolarSys need to incubate? </em></p> |
| <p>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.</p> |
| </li> |
| <li> |
| <p><em>What do all these terms (e.g. EMO) mean? </em></p> |
| <p>Please see the <a href="#glossary">glossary</a>.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="project-resources-and-services">Project Resources and Services</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Open source projects at the Eclipse Foundation are required to make use |
| of certain Eclipse Foundation services:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>All project issues must be tracked in a the issue tracker assigned |
| to the project;</p> |
| </li> |
| <li> |
| <p>Source code must be maintained in source code repositories assigned to the |
| project (e.g. a PolarSys <a href="https://git.polarsys.org/c">Git</a> or <a href="https://git.polarsys.org/r">Gerrit</a> instance, |
| or the <a href="https://github.com/polarsys">PolarSys Organization</a> on GitHub);</p> |
| </li> |
| <li> |
| <p>All third-party libraries used by the project must be tracked and |
| approved for use by the Eclipse IP Team;</p> |
| </li> |
| <li> |
| <p>Downloads must be distributed via a forge-specific downloads server;</p> |
| </li> |
| <li> |
| <p>Developer (committer) communication must occur in the <em>dev</em> list |
| provided to the project by the Eclipse Foundation; and</p> |
| </li> |
| <li> |
| <p>Projects must keep their <a href="#pmi-metadata">Project Metadata</a> up-to-date.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-source">Source Code Management</h3> |
| <div class="paragraph"> |
| <p>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’s assigned |
| distribution channel (e.g. the download server).</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order for your project to operate in an <em>open</em> 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.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="resources-cla">Contributor License Agreement (CLA)</h4> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation has implemented <a href="https://www.eclipse.org/legal/CLA.php">Contributor License Agreements</a> (CLA) |
| to improve <a href="#ip">intellectual property</a> (IP) management and workflow. All |
| contributors, who are not committers on the PolarSys project, must sign the CLA.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You do <strong>not</strong> require a CLA to contribute to a project on which you have committer |
| status.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="resources-commit">Git Commit Records</h4> |
| <div class="paragraph"> |
| <p>Git commit records are required to take a specific form. The credentials |
| of the actual author must be used to populate the <code>Author</code> field. The email |
| address used must match the email address that the Eclipse Foundation has |
| on file for the author (case-sensitive).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The commit message is divided into three sections:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>One line (max 72 characters) summary;</p> |
| </li> |
| <li> |
| <p>Description; and</p> |
| </li> |
| <li> |
| <p>Footer.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="listingblock"> |
| <div class="title">Example Git Commit Record</div> |
| <div class="content"> |
| <pre class="highlight"><code>commit d6cf52411377a039fc2906378711091a26e932cb |
| Author: Some Body <somebody@somewhere.com> <b class="conum">(1)</b> |
| Date: Wed May 29 16:17:36 2013 +0200 |
| |
| Bug 350686 - Hide unwanted action bar items <b class="conum">(2)</b> |
| |
| This change hides unwanted 'Link with Editor' and |
| 'Customize View...' items from the local toolbar |
| and the view menu. |
| |
| Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7 <b class="conum">(3)</b> |
| Also-by: Some Bodyelse <somebodyelse@nowhere.com> <b class="conum">(4)</b> |
| Signed-off-by: Some Body <somebody@somewhere.com> <b class="conum">(5)</b></code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <ol> |
| <li> |
| <p>The email address of the author must match the email address on the Eclipse Foundation account.</p> |
| </li> |
| <li> |
| <p>Best practice: include the bug id in the commit message summary.</p> |
| </li> |
| <li> |
| <p>Gerrit change id (only when pushing to Gerrit for review).</p> |
| </li> |
| <li> |
| <p>Additional authors can be added using <code>Also-by</code> entries.</p> |
| </li> |
| <li> |
| <p>Non-committers must <em>sign-off</em> the commit using the same email address as used in the author field.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>summary</em> line is used in many places where Git commits are listed, ensure |
| that this line is sensible by itself. The <em>description</em> area should be used to provide |
| more detail about the commit. The footer area is used for extra fields and values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>Change-Id</code> is used by <a href="#resources-gerrit">Gerrit Code Review</a> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Create a separate <code>Also-by</code> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Commits that are provided by non-committers must have a <code>Signed-off-by</code> 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 <a href="#resources-cla">Contributor License Agreement</a> (CLA) |
| on file.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="resources-git">Git</h4> |
| <div class="paragraph"> |
| <p>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. |
| <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Git">Open a bug</a> to request that the Webmaster create a new Git |
| repository for your project. Alternatively, committers with shell accounts |
| can create repositories themselves.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">Create a new Git repository</div> |
| <div class="content"> |
| <pre>> initrepo /gitroot/project/org.polarsys.repo.name.git</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For consistency, the name of the repository must end with <code>.git</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To set the description of the repository, use <code>sftp</code> or <code>scp</code> to copy a text file to |
| <code>/gitroot/project/org.polarsys.repo.name.git/description</code>. Git repository |
| descriptions should be limited to a paragraph of one or two sentences.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can <a href="https://git.polarsys.org/c">browse PolarSys repositories</a> directly on the Git server.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="resources-gerrit">Gerrit Code Review</h4> |
| <div class="paragraph"> |
| <p><a href="https://www.gerritcodereview.com/">Gerrit</a> 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. |
| <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Gerrit">Open a bug</a> to request that the Webmaster configure your |
| Git repository for Gerrit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Commits may be pushed directly to the Git repository through Gerrit by |
| a project committer (e.g. to the <code>master</code> branch).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Anybody can push to a <code>refs/for/*</code> 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 |
| <a href="https://git.eclipse.org/r/Documentation/user-changeid.html"><code>Change-Id</code></a></p> |
| </div> |
| <div class="paragraph"> |
| <p>You can <a href="https://git.polarsys.org/r">browse PolarSys repositories</a> directly on the Gerrit |
| server.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="resources-github">GitHub</h4> |
| <div class="paragraph"> |
| <p>Projects may opt to move some or all of their canonical source code repositories to the |
| <a href="https://github.com/polarsys">PolarSys organization</a> on GitHub. Both GitHub Issues and Wiki may also |
| be used.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=GitHub">Open a bug</a> to request that the Webmaster create a new, or move |
| an existing, Git repository for your project. The Webmaster will install some |
| <em>hooks</em> on your GitHub repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>Committers hook</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="#resources-cla">Contributor License Agreement</a> (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 |
| <em>green</em> requests:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/Github-cla-success.png" alt="Github cla success"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/Github-cla-failure.png" alt="Github cla failure"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| <div class="paragraph"> |
| <p>You must manually check that the commit message includes the |
| required "Signed-off-by" statement in the footer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Webmaster creates and maintains a mirror of all GitHub-hosted |
| repositories on Eclipse Foundation hardware.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-issues">Issue Trackers</h3> |
| <div class="paragraph"> |
| <p>PolarSys projects must use an Eclipse Foundation-provided |
| issue tracker. Project teams may opt to use either the <a href="https://www.polarsys.org/bugs">PolarSys Bugzilla</a> |
| instance or—​for projects that use <a href="#resources-github">GitHub</a>--GitHub Issues instances associated |
| with Eclipse Foundation-managed GitHub project repositories.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| Per directive from the Eclipse Foundation’s Board of Directors, |
| you must obtain approval from your PMC to use GitHub Issues. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>To request <em>GitHub Issues</em> access for your project, a bug against |
| <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=GitHub">Community/GitHub</a> and send the link to your PMC’s mailing list |
| with a request for their approval.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-libraries">Third-party Libraries</h3> |
| <div class="paragraph"> |
| <p>PolarSys projects must register all of their <a href="#ip-third-party">third-party library</a> use with the |
| IP Team.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-forums">Forums and Outbound Communication</h3> |
| <div class="paragraph"> |
| <p>All projects are assigned a <a href="http://www.polarsys.org/forums">user forum</a> as a point of contact between |
| the user and adopter communities, and the project developers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-website">Project Websites</h3> |
| <div class="paragraph"> |
| <p>Project websites are an excellent way to connect your project with |
| your community. Many projects opt to use the <a href="#pmi">Project Management Infrastructure</a> |
| (PMI) as their project website, |
| but if so-desired, a project may host a website on Eclipse Foundation-hosted |
| servers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Project website sources are hosted in Git repositories maintained by the |
| Eclipse Foundation. <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Website">Open a bug</a> to request that the Webmaster |
| create a website for your project.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| Alternative hosting services for project-specific websites are |
| not permitted. Websites <em>not</em> hosted by the Eclipse Foundation are |
| considered third-party and so are subject to the |
| <a href="https://eclipse.org/legal/logo_guidelines.php">Guidelines for Eclipse |
| Logo & Trademarks</a> (the Eclipse foundation asserts ownership of the |
| project name trademark). |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-builds">Builds</h3> |
| <div class="paragraph"> |
| <p>Use of Eclipse Foundation-provided and hosted build services, the so-called |
| <a href="http://wiki.eclipse.org/CBI">Common Build Infrastructure</a> (CBI) is strongly recommended, but n |
| ot strictly required.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="resources-signing">Signed Artifacts</h4> |
| <div class="paragraph"> |
| <p>Where technically sensible, all downloadable artifacts should |
| be <a href="https://wiki.eclipse.org/JAR_Signing">signed</a> by an Eclipse Foundation-provided certificate.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="resources-downloads">Downloads</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Project committers can <a href="https://wiki.eclipse.org/IT_Infrastructure_Doc#Downloads">upload project artifacts</a> to the project’s |
| directory on the download server.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="paperwork">Committer Paperwork</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All committers must complete the <em>Committer Questionnaire</em> and provide documentation |
| as described below.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="paperwork-questionnaire">Committer Questionnaire</h3> |
| <div class="paragraph"> |
| <p>The <a href="http://portal.eclipse.org">Committer Questionnaire</a> 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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| The <em>Committer Questionnaire</em> 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Only member companies that have provided a signed Member Committer Agreement |
| will be listed as member companies in the Committer Questionnaire.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="paperwork-documents">Documents</h3> |
| <div class="paragraph"> |
| <p>The exact nature of the documentation required is dependent on your |
| employments status.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/paperwork.png" alt="Paperwork requirements flowchart."> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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 <a href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</a>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="paperwork-mca">Member Committer Agreement</h4> |
| <div class="paragraph"> |
| <p>The <a href="http://www.eclipse.org/legal/committer_process/EclipseMemberCommitterAgreementFinal.pdf">Member Committer Agreement</a> (MCA) is used by member companies to |
| cover all of their employees who participate in Eclipse Foundation projects |
| as committers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If your employer has provided a signed MCA, then you most likely do not |
| require any additional paperwork.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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). |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>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’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 <a href="mailto:emo-records@eclipse.org">EMO Records</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If your employer is a member company that cannot provide a signed |
| MCA, then you’ll have to complete an Individual Committer Agreement and |
| Eclipse Committer Employer Consent Form.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="paperwork-ica">Individual Committer Agreement</h4> |
| <div class="paragraph"> |
| <p>The Individual Committer Agreement (ICA) greement is used by committers |
| who are not covered by an Member Committer Agreement.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You will need to provide an ICA if:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>You work for member company that has not signed a Member Committer Agreement;</p> |
| </li> |
| <li> |
| <p>You work for a company that is not a member of the Eclipse Foundation;</p> |
| </li> |
| <li> |
| <p>You are self employed or not employed; or</p> |
| </li> |
| <li> |
| <p>You are a student.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If you provide an Individual Committer Agreement, and are employed |
| or self-employed, then you also need an <em>Eclipse Committer Employer</em> |
| Consent Form.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="paperwork-ececf">Eclipse Committer Employer Consent Form</h4> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| <div class="paragraph"> |
| <p>You will need to provide an <a href="http://www.eclipse.org/legal/committer_process/employer_consent.pdf">ECECF</a> if:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>You work for member company that has not signed a Member Committer Agreement;</p> |
| </li> |
| <li> |
| <p>You work for a company that is not a member of the Eclipse Foundation; or</p> |
| </li> |
| <li> |
| <p>You are self-employed.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="paperwork-existing">Existing Committer</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="paperwork-not-employed">Not Employed or Student</h3> |
| <div class="paragraph"> |
| <p>If you are not employed or are a student, send a note to <a href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</a> |
| explaining your not employed or student status.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="paperwork-faq">Frequently Asked Questions</h3> |
| <div class="qlist qanda"> |
| <ol> |
| <li> |
| <p><em>What happens if I do not fill out the paperwork?</em></p> |
| <p>Then you don’t get your login and password for write-access to the |
| source code repository(s). Sorry. No exceptions.</p> |
| </li> |
| <li> |
| <p><em>What happens if I cannot convince my employer to fill out the paperwork?</em></p> |
| <p>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’s position <em>even if</em> 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.</p> |
| </li> |
| <li> |
| <p><em>Where can I get help to discuss these documents with my management team? </em></p> |
| <p>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 <a href="mailto:license@eclipse.org">license@eclipse.org</a>.</p> |
| </li> |
| <li> |
| <p><em>What formats can be used to submit paper documentation? </em></p> |
| <p>The Eclipse Foundation accepts any of the following formats for |
| submitting a paper form:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Print, sign, and postal mail the form to the Eclipse Foundation;</p> |
| </li> |
| <li> |
| <p>Print, sign, and fax the form to the Eclipse Foundation; or</p> |
| </li> |
| <li> |
| <p>Print, sign, scan, and email to the scan as an attachment to the Foundation</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>What Email address should I use to send scanned documents? </em></p> |
| <p>Email scans of the completed paperwork to EMO Records at <a href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</a>.</p> |
| </li> |
| <li> |
| <p><em>What if a committer changes employers? </em></p> |
| <p>If you change employers, please contact <a href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</a>.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="ip">Intellectual Property</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>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 |
| <a href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">IP Due Diligence Process</a>, managed by the Eclipse IP Team |
| (commonly referred to as the <em>IP Team</em>), is in place to support this.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All PolarSys committers must be familiar with the <a href="http://eclipse.org/org/documents/Eclipse_IP_Policy.pdf">Eclipse IP |
| Policy</a>.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-initial-contribution">Initial Contribution</h3> |
| <div class="paragraph"> |
| <p>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 <em>initial contribution</em> before <strong>any</strong> code is committed to a project’s |
| source code repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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’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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| A project cannot make a <a href="#release">release</a> until the due diligence on |
| the IP contained in that release—​including project code contributions and |
| third-party libraries—​is complete. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Create a <a href="#ip-cq">contribution questionnaire</a> to submit the initial contribution |
| for review by the IP Team.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 <em>initial contribution</em>, 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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-project-code">Project Code Contributions</h3> |
| <div class="paragraph"> |
| <p>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 <a href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">IP Due Diligence Process</a> |
| provides help to determine whether or not the contribution needs to be reviewed |
| by the IP Team. If you’re not sure, ask your project mentors or your PMC for |
| assistance.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All contributions of project code must be tracked in the project’s |
| <a href="#ip-iplog">IP Log</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Create a <a href="#ip-cq">contribution questionnaire</a> to submit a project code |
| contribution for review by the IP Team.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-third-party">Third-Party Libraries</h3> |
| <div class="paragraph"> |
| <p>All third-party libraries required by project code will have to be checked |
| and approved by the IP Team.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The IP Team must review a third-party library if:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>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);</p> |
| </li> |
| <li> |
| <p>project code includes an import statement for a package from a |
| third-party library;</p> |
| </li> |
| <li> |
| <p>project code uses reflection or other means to reference a |
| library’s APIs and implementation;</p> |
| </li> |
| <li> |
| <p>project code uses OSGi Services to make a reference to a |
| specific implementation of a service; or</p> |
| </li> |
| <li> |
| <p>project code invokes a "command line" tool.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>This list is not intended to be exhaustive.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <a 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</a> can help |
| you determine how to classify your third-party libraries.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| A project cannot make a <a href="#release">release</a> until the due diligence on |
| the IP contained in that release—​including project code contributions and |
| third-party libraries—​is complete. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Create a <a href="#ip-cq">contribution questionnaire</a> to submit a third-party |
| library for review by the IP Team.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-ownership">Ownership</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-copyright-headers">Copyright and License Headers</h3> |
| <div class="paragraph"> |
| <p>All source files must include a file header that describes the copyright and |
| license terms of the software.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">Example Copyright and License Header</div> |
| <div class="content"> |
| <pre>/******************************************************************************* |
| * Copyright (c) 2015 Schmedly Inc. and others. <b class="conum">(1)</b> |
| * 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 <b class="conum">(2)</b> |
| * |
| * Contributors: |
| * Wayne Beaton - initial API and implementation <b class="conum">(3)</b> |
| *******************************************************************************/</pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <ol> |
| <li> |
| <p>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".</p> |
| </li> |
| <li> |
| <p>List project licenses.</p> |
| </li> |
| <li> |
| <p>Optionally list the names of the contributors and the nature of their contribution.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Your project is not a legal entity and so it is inappropriate to list it as |
| the copyright owner.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>For more information please see the <a href="https://www.eclipse.org/legal/copyrightandlicensenotice.php">Default Eclipse Foundation Copyright and License Notice</a>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-licensing">Licensing</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-cq">Contribution Questionnaires</h3> |
| <div class="paragraph"> |
| <p>A Contribution Questionnaires (CQ) is the main interface |
| between PolarSys committers and the IP Team.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A CQ is started when a committer completes a <em>questionnaire</em> regarding |
| a contribution or third-party library. In literal terms, a CQ is a |
| record in a modified instance of Bugzilla, named <em>IPZilla</em>, |
| 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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| You can review existing CQs via <a href="https://dev.eclipse.org/ipzilla">IPZilla</a>. Note that |
| IPZilla is accessible only by committers, Eclipse Foundation member company |
| represenatives, and other specifically-designated individuals. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>All significant contributions of code to be maintained by a PolarSys project, as |
| defined by the Eclipse IP Due Diligence Process require a CQ.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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’s code, you do not require a CQ for that library.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| CQs for third-party libraries are <em>version-specific</em>. That is, |
| a separate CQ is required for different versions of the same library. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>CQs are not generally required for ongoing work done by project |
| committers. Consult the IP Due Diligence Process document for |
| more information.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ip-parallel-ip">Parallel IP</h4> |
| <div class="paragraph"> |
| <p>The <em>Parallel IP Process</em> 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—​with preliminary approval from the IP Team—​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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Parallel IP manifests in two different ways: projects in the |
| <em>incubation phase</em> may leverage the Parallel IP process for |
| project code and third-party libraries. <em>Mature phase</em> projects |
| may leverage parallel IP for new versions of third-party libraries |
| for which previous versions have already been approved.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All IP must be fully approved before it is included in a release.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ip-piggyback">Piggyback CQs</h4> |
| <div class="paragraph"> |
| <p>Many third party libraries have already been approved for use in PolarSys projects. |
| Many of those are immediately available via the <a href="http://www.eclipse.org/orbit">Orbit Project</a>. |
| While these libraries have already been cleared for use by all projects, |
| their use must be tracked. Usage is tracked so that—​in the event that a issue is uncovered |
| following the due diligence process—​we can mitigate the impact of that issue.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this case, a <em>piggyback CQ</em> 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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ip-cq-workflow">CQ Workflow</h4> |
| <div class="paragraph"> |
| <p>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’s Project |
| Management Committee (PMC) before they are processed by the EMO IP Team.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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—​if the CQ meets with the |
| requirements—​tentatively approves the use of the library while the full review is |
| undertaken in parallel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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—​in the event that the library is rejected—​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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-iplog">IP Logs</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The IP Log is a big part of the official <a href="#release">release cycle</a>. You are required to |
| submit your project’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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Specifically, the log tracks:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Licenses;</p> |
| </li> |
| <li> |
| <p>Past and present committers;</p> |
| </li> |
| <li> |
| <p>Third-party libraries; and</p> |
| </li> |
| <li> |
| <p>Contributions from outside the project (i.e. non-committers)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="ip-iplog-generator">IP Log Generator</h4> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The IP Log generator pulls information from multiple location to assemble the log:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/ip-log-generator.png" alt="ip log generator"> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Third-party libraries used by the project come from <em>IPZilla</em>;</p> |
| </li> |
| <li> |
| <p>The <em>Dash</em> process scans the project source code repositories to assess committer activity;</p> |
| </li> |
| <li> |
| <p><em>Dash</em> also scans Git repositories for contributions;</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If you follow the guidelines for handling Git contributions, contributions received via |
| Git in any branch will automatically appear in the log</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p>Contributions received as patches in <em>Bugzilla</em> that are marked <code>iplog+</code> |
| will automatically appear in the log; and</p> |
| </li> |
| <li> |
| <p>License information is obtained from the <em>Foundation</em> database</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>To fully leverage the value of the Automated IP Log Tool, you need to:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Keep your project metadata up-to-date;</p> |
| </li> |
| <li> |
| <p>Follow the guidelines for handling Git contributions;</p> |
| </li> |
| <li> |
| <p>Mark IP Contributions in Bugzilla; and</p> |
| </li> |
| <li> |
| <p>Create <a href="#ip-cq">contribution questionnaires</a> (CQs) where appropriate</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Warning</div> |
| </td> |
| <td class="content"> |
| Contributions should be recorded in <em>one of</em> Git or Bugzilla, not both. |
| Setting the <em>Author</em> credentials on Git commits is the preferred mechanism. |
| The IP Log generator is not smart enough to detect duplicate entries. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Your project’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 <em>Source Repositories</em> section, a list of paths to source code |
| repository locations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Automated IP Log tool populates the <em>Contributors</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p><a href="#resources-commit">Git commits</a> contributed by non-committers are identified by |
| the author credentials on the commit record; the <em>Author</em> field must be set to the identity |
| of the actual author of the commit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, Bugzilla attachments can be marked with the <code>iplog+</code> 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 <strong>must</strong> 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’s |
| repository and flagging the entry.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can also flag an entire Bugzilla entry with <code>iplog+</code>. 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’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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>That contributions flagged in Bugzilla will only appear in the IP Log if the bug is marked |
| <code>FIXED</code> or <code>CLOSED</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 |
| <a href="mailto:emo-ip-team@eclipse.org">EMO IP Team</a> to make corrections.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ip-faq">Frequently Asked Questions</h3> |
| <div class="qlist qanda"> |
| <ol> |
| <li> |
| <p><em>Do we really need to do this? </em></p> |
| <p>Yes.</p> |
| </li> |
| <li> |
| <p><em>What do you do with the IP Log? </em></p> |
| <p>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.</p> |
| </li> |
| <li> |
| <p><em>When should I submit the IP Log for review? </em></p> |
| <p>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.</p> |
| </li> |
| <li> |
| <p><em>Are there other reasons to submit the IP Log for review? </em></p> |
| <p>Generally no. If the IP Team requires an IP Log review outside of the context of |
| a release or restructuring review, they’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.</p> |
| </li> |
| <li> |
| <p><em>How do I fix problems with the generated IP Log? </em></p> |
| <p>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 <a href="mailto:emo@eclipse.org">emo@eclipse.org</a>.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="release">Releases</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>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’d like. It’s |
| common practice to specify releases three or six months into the future.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Releases are broadly categorized as:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><em>Major</em> releases include API changes (potential for downstream breakage);</p> |
| </li> |
| <li> |
| <p><em>Minor</em> releases add new functionality, but are API compatible with previous versions; and</p> |
| </li> |
| <li> |
| <p><em>Service</em> releases include bug fixes only and include no significant new functionality.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For all major and minor releases, you must engage in a <em>release review</em>. |
| Release reviews are not required for bug-fix/service releases.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/release-cycle.png" alt="The release cycle"> |
| </div> |
| </div> |
| <div id="releases-plan" class="paragraph"> |
| <p>A project plan is <em>required</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Use the <a href="#pmi">Project Management Interface</a> 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’s <em>dev</em> list |
| and other project channels.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>Plan</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 <em>milestone</em> 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’s downloads page provides the information required for the |
| community to obtain your builds.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All of your project’s <a href="#ip">intellectual property</a> 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).</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="release-review">Release Review</h3> |
| <div class="paragraph"> |
| <p>A <em>release review</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Release reviews run for a week and always conclude on a Wednesday.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| We schedule reviews to conclude on the <em>first and |
| third Wednesdays of the month</em>. 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A <em>release review</em> 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 <em>review</em> date.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/release-review.png" alt="Release review work flow"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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 <em>Review</em> 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’s |
| no need to wait until the end)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The review materials must be approved by the PMC; send an email to |
| the PMC’s mailing list asking for approval. The PMC will respond with |
| feedback or a simple "+1" indicating approval.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| Click the handy <em>Send Email to the PMC</em> link under <em>Committer Tools</em> |
| on the release record page to connect with the PMC. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>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 <a href="#ip-iplog-generator">IP Log generator</a> automatically |
| collects information based on the information that the project team has |
| provided to the IP Team through <a href="#ip-cq">contribution questionnaires</a> |
| in IPZilla, commits in the project’s source code repository, and |
| other information in our databases. Carefully review the IP Log before |
| submitting to the IP Team for their review.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| Click the handy <em>Generate IP Log</em> link under <em>Committer Tools</em> |
| on the release record page to open the IP Log generator. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The information used to generate an IP Log should always be up-to-date |
| (don’t wait until the end of the release cycle to make it right).</p> |
| </div> |
| <div class="paragraph"> |
| <p>At any point in this process, you can request that the review be |
| initiated by clicking the <em>Schedule a review for this release</em> 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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| The EMO will likely notice that you’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 |
| <a href="mailto:emo@eclipse.org">emo@eclipse.org</a> stating your intent to release. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The EMO will conclude the review on the scheduled end date and advise the |
| project team of the outcome.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="release-graduation">Graduation Review</h3> |
| <div class="paragraph"> |
| <p>The purpose of a <em>graduation review</em> 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 <a href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</a>; and |
| is a credit to PolarSys and is functioning well within the larger PolarSys community</p> |
| </div> |
| <div class="paragraph"> |
| <p>Graduation reviews are generally combined with a <a href="#release-review"><em>release review</em></a> |
| (typically, but not necessarily the <em>1.0</em> release). |
| Upon successful completion of a graduation review, a project will leave the |
| incubation phase and be designated as a <em>mature</em> project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a graduation review, release review documentation must be augmented to |
| include demonstration of:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>solid working code with stable APIs;</p> |
| </li> |
| <li> |
| <p>an established and growing community around the project;</p> |
| </li> |
| <li> |
| <p>diverse multi-organization committer/contributor/developer activity; and</p> |
| </li> |
| <li> |
| <p>operation in the open using open source rules of engagement.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>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".</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="release-faq">Frequently Asked Questions</h3> |
| <div class="qlist qanda"> |
| <ol> |
| <li> |
| <p><em>Can a release review fail? </em></p> |
| <p>Technically, yes. A release review can fail. In our history, however, this |
| occurrs very rarely. We set up release reviews to succeed.</p> |
| </li> |
| <li> |
| <p><em>Do we really need to do this? </em></p> |
| <p>Yes.</p> |
| </li> |
| <li> |
| <p><em>How often should we do releases? </em></p> |
| <p>This depends very much on the nature of your project and the expectations |
| of your community and stake holders. If you’re not sure, connect with your |
| mentors and top-level project for guidance.</p> |
| </li> |
| <li> |
| <p><em>How much effort should we put into this? </em></p> |
| <p>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’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’s PMC, or the |
| <a href="mailto:emo@eclipse.org">EMO</a> for guidance.</p> |
| </li> |
| <li> |
| <p><em>How do I submit the IP Log for review? </em></p> |
| <p>Click the <em>Submit</em> button on the <a href="#ip-iplog-generator">IP Log generator</a>. |
| You need to be logged in as project committer to have access to this button.</p> |
| </li> |
| <li> |
| <p><em>Can I accept contributions after I submit the IP Log for review? </em></p> |
| <p>The short answer is <em>yes</em>. 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 <a href="mailto:emo-ip-team@eclipse.org">IP Team</a> if |
| they want you to resubmit the IP Log.</p> |
| </li> |
| <li> |
| <p><em>How do I obtain PMC approval? </em></p> |
| <p>Send the the PMC a note via the top-level project’s <em>PMC</em> mailing list |
| with a link to the release record. Note that the release record page |
| has a handy link labeled <em>Send Email the PMC</em> under <em>Committer Tools</em>.</p> |
| </li> |
| <li> |
| <p><em>I need to do a release now. Can you fast-track the review? </em></p> |
| <p>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.</p> |
| </li> |
| <li> |
| <p><em>Can a project in the incubation phase do releases? </em></p> |
| <p>Yes. In fact, we encourage projects to do at least one release while |
| in incubation phase.</p> |
| </li> |
| <li> |
| <p><em>What restrictions are placed on version names for incubating projects? </em></p> |
| <p>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’re not sure, ask your top-level project PMC for advice.</p> |
| </li> |
| <li> |
| <p><em>How do I name/number milestone builds? </em></p> |
| <p>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".</p> |
| </li> |
| <li> |
| <p><em>How can I get help? </em></p> |
| <p>Contact your mentors (for projects in the incubation phase), top-level |
| project PMC, or the <a href="mailto:emo@eclipse.org">EMO</a>.</p> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="pmi">Project Management Infrastructure (PMI)</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The PolarSys Project Management Infrastructure (PMI) consolidates |
| project management activities into a single consistent location and experience.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Project Management Infrastructure themes:</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Improved consistency.</em> Configuration/data-driven project web presence, |
| direct linkage between releases, reviews, and plans. Information—​including |
| basic project metadata, project plans, and release review information—​is |
| captured and retained in a consistent (and easily leveraged) data-based |
| format (rather than in multiple documents in arbitrary formats).</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>All-in-one-place.</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Get started faster.</em> 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.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="pmi-metadata">Project Metadata?</h3> |
| <div class="paragraph"> |
| <p>Project committers and project leads are responsible for maintaining |
| their project’s metadata. This information is an important part of being |
| an Eclipse project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Project metadata is:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Relatively static structural information such as the project |
| description and scope, the names of the project’s mailing lists and |
| newsgroups, the bugzilla products, source code repositories, etc.</p> |
| </li> |
| <li> |
| <p>Historical information such as previous release downloads, release |
| review slides and IP logs, etc.</p> |
| </li> |
| <li> |
| <p>Status and future looking information such as the project and |
| milestone plans, the features scheduled for the current release, release |
| dates, etc.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>PMC members, and the Eclipse Foundation staff also have the ability to |
| make changes on behalf of a project.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="pmi-viewing">Viewing</h3> |
| <div class="paragraph"> |
| <p>The complete listing of all current |
| <a href="http://www.polarsys.org/list-of-projects">PolarSys projects</a> 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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="pmi-commands-and-tools">Commands and Tools</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="pmi-editing">Editing Project Metadata</h3> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Some of the fields are described below.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-description-and-scope">Description and Scope</h4> |
| <div class="paragraph"> |
| <p>The <em>description</em> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 <em>Teaser Break</em> into the content.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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 <em>weird</em>. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>scope</em> is intended for a more select audience; generally speaking the |
| scope should be taken directly from the project’s proposal. Project |
| members have the ability to change the text of the project scope, but |
| should be careful to avoid changing the meaning. If the meaning of the |
| scope needs to change, the Project Management Committee (PMC) must be |
| contacted regarding a potential restructuring review.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-downloads">Downloads</h4> |
| <div class="paragraph"> |
| <p>You can provide download information for your project in the "Downloads" |
| section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="source-repositories">Source Repositories</h4> |
| <div class="paragraph"> |
| <p>The project can specify zero or more <strong>source repositories</strong>. These are |
| displayed in the "Contribute to this Project" section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Repositories should be specified using the file system path, e.g. |
| <em>/gitroot/egit/egit.git</em>. The name that is displayed for the repository |
| is extracted from the last segment of the URL.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a description file exists in the Git repository, the contents are |
| automatically displayed under the repository name.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| 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. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>You can use wildcards to match multiple repositories, e.g. |
| <em>/gitroot/virgo/*</em>. Note that wildcards only work for repositories that |
| exist on PolarSys infrastructure (they do not work for GitHub-based |
| repositories, for example).</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A <strong>Contribution Message</strong> 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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-company-logos">Company Logos</h4> |
| <div class="paragraph"> |
| <p>Company logos automatically appear on the <em>Who’s Involved</em> page under the following |
| conditions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The company must be a <a href="http://eclipse.org/membership/">member</a> of the |
| Eclipse Foundation;</p> |
| </li> |
| <li> |
| <p>The company needs to have their logo uploaded to the Portal;</p> |
| </li> |
| <li> |
| <p>At least one committer has to be listed as an employee of the company |
| in question;</p> |
| </li> |
| <li> |
| <p>The committer must be on this project; and</p> |
| </li> |
| <li> |
| <p>The committer must be active (must have made at least one commit in |
| the last three months)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If all of those conditions are met and the logo is still not showing up, |
| then it’s possible that the project meta-data doesn’t have the correct |
| source code repository information specified.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-build-technology">Build Technology</h4> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-technology-types">Technology Types</h4> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="pmi-releases">Releases and Reviews</h3> |
| <div class="paragraph"> |
| <p>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 <em>review</em> 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.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="images/ProjectsReleasesReviews.png" alt="Releases and Reviews"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each <a href="#release">release</a> 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.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| _Create a single record for each release. <strong>Do not create release records |
| for milestones.</strong> Enter milestone information in the <em>Plan</em> information |
| for your release. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-release-description">Description</h4> |
| <div class="paragraph"> |
| <p>Describe the release in the <em>Description</em> 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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-release-issues">Issues</h4> |
| <div class="paragraph"> |
| <p>The release record will automatically generate a list of targeted bugs.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To populate this list:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Ensure that the Bugzilla Product is set the to correct value in the |
| project metadata;</p> |
| </li> |
| <li> |
| <p>Set the "target milestones" in Bugzilla need to match the name of your |
| release.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <div class="title">Note</div> |
| </td> |
| <td class="content"> |
| The matching algorithm tries to be as forgiving as possible, a release |
| named "3.5", "3.5.0", or "3.5 (Luna)" will—​for example—​match target |
| milestones named "3.5" ,"3.5M1", "3.5 M2", "3.5.0M3", etc., but will |
| not match "3.5.1". |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The bugs for all projects participating in the release will be included. |
| Bugs are grouped by Bugzilla product and component.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-release-plan">Plan</h4> |
| <div class="paragraph"> |
| <p><a href="#releases-plan">Project plan</a> information belongs in the <em>Plan</em> section. This |
| information <strong>should</strong> 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).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-release-milestones">Milestones</h4> |
| <div class="paragraph"> |
| <p>Enter the name, date, and optional description for each milestone |
| expected with the release.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pmi-review">Review</h4> |
| <div class="paragraph"> |
| <p>The release has a <a href="#release-review"><em>Review</em></a> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each section on the review page includes a little help to describe the |
| sort of information that you should provide.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can edit the review document, but there’s really not all that much |
| to edit. A free-form text field is available and can be used if there is |
| some need to provide review-specific information that might not |
| otherwise be an appropriate part of the release record. <em>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.</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>When the review is displayed, it automatically includes the <em>review</em> |
| information from the release record; it shows the review-specific |
| information at the top of the page, and includes the <em>review</em> |
| information from the release as the rest of the page contents.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This can make things a bit confusing when you want to make changes to |
| the metadata for a review record. Just remember that the <em>review</em> |
| information for a release is stored in the release record.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="glossary">Glossary</h2> |
| <div class="sectionbody"> |
| <div class="dlist glossary"> |
| <dl> |
| <dt>Architecture Council </dt> |
| <dd> |
| <p>The Eclipse Architecture Council (AC) serves the community by identifying and |
| tackling any issues that hinder Eclipse’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’s |
| goal to keep the projects successful and healthy, the processes simple and smooth, |
| and the communities vibrant and cohesive.</p> |
| </dd> |
| <dt>Architecture Council Mentor </dt> |
| <dd> |
| <p>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’t have an answer to your question, they can draw |
| on the wisdom of the full AC and the EMO.</p> |
| </dd> |
| <dt>Board of Directors </dt> |
| <dd> |
| <p>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").</p> |
| </dd> |
| <dt>Committer </dt> |
| <dd> |
| <p>A committer is a software developer who has the necessary rights to write code |
| into the project’s source code repository. Committers are responsible for ensuring |
| that all code that gets written into the project’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.</p> |
| </dd> |
| <dt>Community </dt> |
| <dd> |
| <p>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 <em>PolarSys Community</em> is formed from the union of the communities that grow |
| around individual projects.</p> |
| </dd> |
| <dt>Contribution Questionnaire </dt> |
| <dd> |
| <p>Prior to committing a significant contribution of content from a non-committer |
| to a PolarSys project, the committer must fill out a <a href="#ip-cq">contribution questionnaire</a> (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 <a href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">Eclipse IP Due Diligence Process</a>.</p> |
| </dd> |
| <dt>Contributor </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>Dash Process </dt> |
| <dd> |
| <p>The Dash Process, or simply <em>Dash</em>, is a collection of scripts and processes that |
| harvest project data for dissemination in charts, <a href="#ip-iplog">IP Logs</a>, and more.</p> |
| </dd> |
| <dt>Dev-list </dt> |
| <dd> |
| <p>Every project has a <em>development list</em> or <em>dev-list</em>. 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’s automated systems communicate with the project.</p> |
| </dd> |
| <dt>Ecosystem </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>Eclipse </dt> |
| <dd> |
| <p>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—​of course—​The Eclipse Project (which is just one of |
| the top-level projects hosted by the Eclipse Foundation). Confusing? Yes.</p> |
| </dd> |
| <dt>EMO </dt> |
| <dd> |
| <p>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 (<a href="mailto:emo@eclipse.org">emo@eclipse.org</a>). |
| If you have a question that cannot be answered by project lead, mentor, or PMC, ask the EMO.</p> |
| </dd> |
| <dt>EMO Executive Director </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>EMO IP Team </dt> |
| <dd> |
| <p>The EMO Intellectual Property Team (commonly referred to |
| as the <em>IP Team</em>) is responsible for implementing the intellectual |
| property policy of the Eclipse Foundation.</p> |
| </dd> |
| <dt>EMO Records </dt> |
| <dd> |
| <p>The EMO Records Team (commonly referred to as <em>EMO Records</em>) is |
| responsible for managing committer paperwork and other records |
| on behalf of the Eclipse Foundation. Contact the EMO Records team via email |
| (<a href="mailto:emo-records@eclipse.org">emo-records@eclipse.org</a>).</p> |
| </dd> |
| <dt>Incubation Phase </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>IP Due Diligence Process </dt> |
| <dd> |
| <p>The <a href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">Intellectual Property Due Diligence Process</a> defines the process by which |
| intellectual property is added to a project. All PolarSys committers must be familiar |
| with this process.</p> |
| </dd> |
| <dt>IP Log </dt> |
| <dd> |
| <p>An <a href="#ip-iplog">IP Log</a> 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.</p> |
| </dd> |
| <dt>Member Company </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>Parallel IP </dt> |
| <dd> |
| <p>The <a href="#ip-parallel-ip">Parallel IP Process</a> allows a PolarSys projects to make use of |
| project code contributions and third-party libraries before they |
| are fully approved by the IP Team.</p> |
| </dd> |
| <dt>Planning Council </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>Project</dt> |
| <dd> |
| <p>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 <em>subprojects</em> or as <em>components</em>. The Eclipse Development Process, however, |
| treats the terms project, subproject, and component as equivalent.</p> |
| </dd> |
| <dt>Project Lead </dt> |
| <dd> |
| <p>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’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 <a href="http://www.eclipse.org/projects/dev_process/development_process.php">Eclipse Development Process</a>, or anything else, ask |
| your project lead.</p> |
| </dd> |
| <dt>PMC </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>PMI </dt> |
| <dd> |
| <p>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.</p> |
| </dd> |
| <dt>Top-Level Project </dt> |
| <dd> |
| <p>A top-level project (sometimes referred to as a <em>TLP</em>) 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.</p> |
| </dd> |
| <dt>Webmaster </dt> |
| <dd> |
| <p>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 (<a href="mailto:webmaster@eclipse.org">webmaster@eclipse.org</a>).</p> |
| </dd> |
| <dt>Working Group </dt> |
| <dd> |
| <p>Eclipse <a href="https://www.eclipse.org/org/workinggroups">Working Groups</a> provide |
| a vendor-neutral governance structure that allow organizations to freely |
| collaborate on new technology development.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="contact">Getting Help</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>If you have any questions, or are unsure of your responsibilities as a |
| project lead or committer, please contact your project mentors or |
| <a href="mailto:emo@eclipse.org">EMO</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="footer"> |
| <div id="footer-text"> |
| Last updated 2015-08-18 15:09:59 -04:00 |
| </div> |
| </div> |
| </body> |
| </html> |