<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<title>The Eclipse Simultaneous Release</title>
</head>
<body>
<h1 style="text-align: center">The Eclipse Simultaneous Release</h1>
<h1 style="text-align: center; font-size: smaller">December 2, 2009<br />
<a href="http://wiki.eclipse.org/Planning_Council">Eclipse Planning Council</a><br />
Contact: <a href="mailto: david.williams@eclipse.org">David Williams</a></h1>


<p>This document defines the rules and criteria for participating in
the yearly Simultaneous Release. There are more criteria than when
releasing at other times partially because there are more projects
releasing at once, so the workload needs to streamlined and made more
uniform. More important, the extra criteria are included by mutual
agreement between projects (via their representatives to Planning
Council) so that as a whole, the release will be of better quality,
maintainability, and improved consumability by adopters.</p>
<p>The spirit of this document should not be so much as a "contract" of what has 
to be done to release, but instead as an agreement to make the 
Yearly Release good, if not great! While each Project does their individual things 
to make the Release great, this document and process describe how we as a group document 
the achievement of our agreement. We are always open to 
better agreements and better documentation of our achievements so feel free to keep track and make 
suggestions year-to-year (preferably through your Planning Council representative) on how to make our 
yearly release better. In fact, occasionally changes may be made to this document for 
clarity or to improve reference links throughout the development cycle,
but nothing new that would change work-load will be added after M4.</p>
<p>To foster communication and flexibility where required,  
any exceptions to these criteria or deadlines will follow the <a
       href="#pcExceptionProcess">Planning Council Exception Process</a>.</p>
<p>The requirements are divided into three
categories:</p> 
<ol><li>Requirements to be released as part
of the &quot;yearly release&quot;, normal release requirements, done earlier than usual.</li> 
<li>Requirements to be
part of the Common Discovery Site repository and, consequently, the minimum requirements to be 
part of EPP packages.</li>
<li>Requirements to demonstrate good Eclipse Citizenship, following
&quot;the Eclipse Way&quot;.</li>
</ol>

<h2>Do the basics ... early</h2>
<p>The requirements and conditions stated in this section are the
basic minimum required for a project to claim they are part of the
yearly Simultaneous Release.</p>
<p>To join a Simultaneous Release, Projects must have stated their
intent to do so, and be in a build for the composite site aggregation by
M4, at the latest. For projects continuing from previous years, the
expectation is they will be in M1, unless they formally withdraw.</p>
<p>The &quot;statement of intent&quot; is done formally by marking
the &quot;Simultaneous Release Flag&quot; in the project's Portal
meta-data.</p>
<h3>Planning</h3>
<p>All projects must have their project plan in the Eclipse
Foundation standard XML Format (a normal Eclipse requirement).
Committing to be in the Simultaneous Release means you commit to having
these plans early: M2, for those projects that already know they will be
in the Simultaneous Release, M4 will be the latest possible time, for
those projects that are new to the Simultaneous Release Train and decide
to join after M2. The plans should be updated periodically as things 
change, or as items are completed.</p>
<p>Also, for long term planning, remember that being in a
Simultaneous Release also means a commitment to participating the SR1
and SR2 simultaneous maintenance releases.</p>
<p><i>[New this year.]</i> Once in, always in. Once a project joins
one year's Simultaneous Release, it is assumed they will be in the next
one, unless they formally withdraw. So, for example, it is required they
will meet the subsequent year's Milestone Schedule, have plans done by
M2 of following year, etc. Put another way, being part of the
Simultaneous Release is not a &quot;one time&quot; activity, covering
only the literal release date and not even a &quot;part time&quot;
activity covering only part of the yearly development cycle. Instead it
is a commitment to stay &quot;simultaneous&quot; on an on-going basis.</p>


<h3>IP Documentation</h3>
<p>Projects must have their IP Logs approved (a normal Eclipse
requirement) and will follow the Eclipse Legal deadlines to do so. In
addition, drafts of the Projects IP Logs must be available early, starting with M5. The development process requires the IP Log to always be accurate, but experience shows there's always some issues that have to be resolved, or fixed, before release (for example, sometimes a CQ might have the wrong flag, and cause it to not show up in the Auto IP Log). It is expected the IP Logs should be
relatively complete by M7. If Projects have changes come in after M7
they can update until the deadline set by the IP staff (usually RC2).
The purpose of having these early drafts is so that projects get
familiar with what's required, and do not allow work to build up at the
end, also to allow questions to come up, and have time to find answers,
and also to allow time for issues with automatic IP tools to be
addressed. Some adopters will want to look at these early drafts to see what 3rd party requirements are associated with the code. </p>
<p>Being in the Simultaneous Release will give your IP some higher
priority in getting evaluated, in order to make the date. The higher
priority treatment is only for the 5 months or so before the release
(after the deadline for CQs). The reason being, of course, is that the
rest of the year the IP staff must also get work done for maintenance
releases and projects not on the release train. During that part of the
year (roughly July to February every year) all CQs are prioritized in a
uniform way.</p>
<h3 id="pcReleaseReview">Release Review</h3>
<p>The release review archival materials must be complete by the
date specified by the EMO, which is usually staged in earlier than for a
usual release. (Typically RC2.)</p>
<p>A Project's PMC must approve the projects request for review (a
normal Eclipse requirement). In addition, to help organize and
streamline the yearly Simultaneous release, a PMC must provide their
approval in writing, in the form of a short summary of their projects
that are requesting review and summary of the PMC's discussion or method
of approving them. (This is meant to be very brief, such as 1/2 to 1
page). The short summary can be documented in a mailing list, PMC
Meeting notes, or even a wiki document. A pointer (URL) to the document
should be provided to EMO, and will be included in the same notice to
the community that provides pointers to the Project Docuware.</p>
<p>The public review calls will be organized based on Top Level
Project, and at least one PMC member should be on that call to give very
brief overview of projects that are requesting the release review (not
to exceed 5 minutes, at the very most).</p>
<p>In addition to the ordinarily required Release Review Archival
Materials, all Projects participating in yearly Release agree to provide
a checklist-with-detail form that describes their compliance (or not)
with all of the criteria items described in this document. Note that
this checklist-with-detail must be updated every milestone as things are
completed, or details added, so progress can be reviewed by Planning
Council and potential adopters. The primary report of compliance with
the checklist must be provided at least at the level of a Top Level
Project. In some cases, such as if sub-projects are very independent of
each other, PMCs may decide to document things at a subproject level,
and then &quot;roll-up&quot; to a Top Level document, or, if a Top Level
Project is known to be uniform and &quot;close knit&quot; then they may
provide one summary document that applies to all sub-projects. [This will likely be 
automated as web-app, possibly with
&quot;automatic&quot; roll up].</p>
<p></p>
<h2>Play well with others ... to be in common repository</h2>
<p>The requirements in this section must be met for a project to be
on the common, central repository (e.g. /releases/helios) for end users
to discover easily and minimum requirements to be included in EPP Packages. The criteria in
this section are designed to make sure projects work relatively well, and work well
together. This is especially required for adopters who may be using
these projects in complicated, interwoven ways so each piece of the
puzzle must fit together well and be dependable and be maintainable, as
well as being on time and IP clean.</p>
<p><b>Communication</b>: 
<p>At least one person from each project in a Simultaneous Release
must subscribe to cross-project mailing list, since that is the primary
communication channel for issues related to the Simultaneous Release.
Also, at least one person from each project must subscribe to
cross-project bugzilla inbox, as that is the primary bugzilla components
for bugs that are truly cross-project, or bugs which are not known to be
in one particular component.</p>
<p>Your representative to the Planning Council, either from PMC or
Strategic Member, must attend PC meetings and represent you there.
Presumably, of course, after meeting or communicating with you and the
other projects they represent, so they can fairly bring forward concerns
and vote on issue that effect all projects, if required. Put another
way, by committing to be in the Simultaneous Release, you agree to abide
by all the Planning Council decisions and rules, so be sure your
representative understands your project and your situation.</p>
<p>Build team members (or their designated
alternates) from each project may be asked to provide direct
communication channels: phone, mail, IM, IRC and at least one build team
member must be &quot;on call&quot; during the milestone integration
periods.</p>
<p><b>API</b>. Projects should leverage only published APIs of
dependencies. All deviations must be documented in bugzillas. These
bugzillas may be of the type that a dependent project should provide a required
API, or of the type that a consuming project must move to some API that
already exists. Note that technically there is no obligation for
consumed projects to provide API that is requested ... that depends on
many things ... but the main goal of requiring these bugzilla entries is to provide some documentation 
and measure of the
amount of risk associated with non-API use.</p>
<p><b>Message Bundles</b>. Projects must use <a
       href="http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/reference/misc/message_bundles.html">
Eclipse message bundles</a> unless there are technical reasons not to.</p>
<p><b>Version Numbering</b>. Projects must use 4-part <a
       href="http://wiki.eclipse.org/Version_Numbering">version numbers</a>.</p>
<p><b>OSGi bundle format</b>. All plug-ins (bundles) must use the
true bundle form. That is, provide a manifest.mf file, and not rely on
the plugin.xml file being 'translated' into a manifest.mf file at
initial startup. With that, empty plugin.xml files in the presence of a
manifest.mf file should not be included in a bundle. (For some old
history, see <a
       href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=130598">bug
130598</a>.)</p>

<p><b>Execution Environment</b>. All plug-ins must <a
       href="http://wiki.eclipse.org/Execution_Environments">correctly
list their Bundle Required Execution Environment (BREE)</a>.</p>

<p><b>Signing</b>. Projects must use <a
       href="http://wiki.eclipse.org/JAR_Signing">signed plugins using the
Eclipse certificate</a>.</p>

<p><b>Jarred Bundles</b>. Projects must use jarred plug-ins (with
unpack=false) unless authorized by the planning council for technical
exceptions. Also, nested jars should be avoided if possible since it
creates problems for projects that has dependencies to such plug-ins.
The OSGi runtime is fine with it but the PDE environment is not able to
handle classpaths that contain nested jars.</p>
<p><b>Re-use and share</b><b> </b>common third party jars. Any
third-party plug-ins that are common between projects must be consumed
via <a href="http://www.eclipse.org/orbit">Orbit</a>; a Simultaneous
Release will not have duplicate third-party libraries (note that this
only applies to identical versions of the libraries; thus if project A
requires foo.jar 1.6 and project B uses foo.jar 1.7, that's ok, as long
as it is required and has a documented reason).</p>

<p><b>Optimization</b>. Projects must <a
       href="http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/guide/p2_repositorytasks.htm">
optimize their p2 repositories</a> to reduce bandwidth utilization and
provide a better install and update experience for users.</p>
<p><b>Provide p2 repository</b>. Projects must provide their own
project p2 repository for their own project and updates. In addition,
they must provide their archives and metadata in a specified format and method to allow
at least parts of their repository to be aggregated and mirrored to a
common repository. The <a href="http://wiki.eclipse.org/Helios/Contributing_to_Helios_Build">current process</a> may be modified throughout the year, if improvements can be made. Clarification on 03/31/2010: At the <a
	href="http://wiki.eclipse.org/Planning_Council/March_21_2010#Helios">3/21
Planning Council meeting,</a> it was agreed this means that project's repositories must contain original jars, and pack.gz files (where original jar means the jar produced by the build, but which has been conditioned for pack200). </p>
<p><b>Capabilities</b>. Each project will provide basic
capability/activity definitions to allow for their UI contributions to
be hidden. These may be provided in a separate plugins and features to
facilitate inclusion and reuse by consumers in product development, or simply well 
documented so adopters
can reuse via copy/paste. Ideally, projects should also provide 
triggers to facilitate progressive discovery of functionality. 
</p>
<p><b>Support Translations</b>. All strings must be externalized,
and Projects must participate in Babel, meaning it is registered and
available for string translation, etc. Projects must freeze the UI
sufficiently early to allow the Babel project time to translate strings
so there can be simultaneous release of translated versions. The UI
should be frozen by M6 (a "freeze" all major changes and additions are done
by M6, and changes after that are done in a controlled, well documented fashion, 
so Babel translators can more easily &quot;keep
up&quot; with late changes).</p>
<p><b>Excel in NL support</b>. The Project must use <a
       href="http://wiki.eclipse.org/ICU4J">ICU4J</a>, where appropriate, to
excel in NL support. (The latest ICU4J bundles will be in Orbit).</p>
<p><b>Branding</b>. Each major project (as determined by
participating PMCs) must have an 'About' dialog icon with hover text
that displays the provider name. Every plug-in and feature must specify
a descriptive provider-name (for features), or Bundle-Vendor header (for
plug-ins), as determined by the project's PMC (e.g. "Eclipse Modeling
Project" rather than "Eclipse.org"). Also, Projects must contribute to
the welcome page when appropriate.</p>


<p><b>Do No Harm.</b> Projects must work together in any combination
of any install. Put another way, this means that users can install any
subset of the Helios projects and each of the installed projects will work as well
as if it had been loaded independently. If such
a problem is identified, the affected projects must track down and fix
the problem.</p>
<p><i>[New this year.]</i> <b>License text consistency</b>. Use standard
forms of license documents so it is displayed in the most usable, and
concise way during install and update. It is a normal requirement to use a standard
<a
       href="http://www.eclipse.org/legal/epl/about.php">Eclipse
Foundation &quot;about&quot; template</a>, but where those templates are
edited by each project, care must be taken to be sure they are edited in
similar ways. You can see an example of the license-consolidating UI in
<a
       href="http://download.eclipse.org/eclipse/downloads/drops/S-3.6M1-200908061400/eclipse-news-M1.html#Platform">Eclipse
Platform Helios M1</a>.</p>


<h2>Be a good Eclipse Citizen ... and document it</h2>
<p>Projects should exhibit good Eclipse Citizenship, to Release and participate
in Common Discovery Site and EPP Packages. These are often &quot;best
practices&quot; that some projects have found helpful at Eclipse. These
criteria often speak to the quality of the Project, as an Eclipse
Project, as opposed to their code or architecture. They are a bit more
subjective than some of the other criteria, and the relevancy to any
particular project may not be as universal, so there is no set number of
items to satisfy. But, it is required that each project document their level of
compliance to each item. Especially good Eclipse Citizens will get a
gold star, and especially bad ones might get a frowny face.</p>
<p><b>Engage Community</b>. The Project should actively engage their
community to get feedback on milestone builds, and document how they do
that. One way to do this is to have a <a
       href="http://wiki.eclipse.org/Architecture_Council/New_and_Noteworthy">New
&amp; Noteworthy</a> for each milestone. New and Noteworthy documents should
be something readable and usable not just a static list of all the bugs.
Corollary: individual new &amp; noteworthy should be linked in to the
collective New &amp; Noteworthy.</p>
<p><b>Usability</b>. Should follow the <a
       href="http://wiki.eclipse.org/User_Interface_Guidelines">User
Interface Guidelines</a>. The <a href="http://wiki.eclipse.org/UI_Checklist">UI
Checklist</a> is a good place to start. Also, should participate in a <a
       href="http://wiki.eclipse.org/User_Interface_Best_Practices_Working_Group">User
Interface Best Practices Working Group</a> <a
       href="http://wiki.eclipse.org/UIBPWG_UI_Walkthrough"> UI
walkthrough</a>.</p>
<p><b>Performance</b>. Project should have measurable performance
criteria that are regularly tested against. Projects should devote at
least one milestone to performance and scalability improvements.</p>
<p><b>Test Localization</b>. The project should use the <a
       href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=217339">Babel
Pseudo Translation Test</a> to verify their translatability. [Need better reference link.]</p>
<p><b>Enable Use with All Languages</b>. Should design and test for
enabling all languages including bidi, unicode characters, etc. This is different than "translating" 
the program. For example, while using an English version of Eclipse Web Tools, someone should be able to create 
a Chinese language web application.  
[Need "how to" reference link.]</p>
<p><b>Builds</b>. Projects must have a mature, stable build process:
documented, scripted, repeatable, and executable by others.</p>
<p><b>Ramp Down Planned and Defined</b>. Projects must have a
written ramp down policy by M6, at the latest, and provide link. The
plan should describe when the project plans to be feature complete, have
API frozen, and similar. See <a
       href="http://www.eclipse.org/eclipse/development/freeze_plan_3.5.php">Platform
3.5 Endgame plan</a> as a guideline. See also <a
       href="http://wiki.eclipse.org/heliosPlan/index.php?title=Helios/Final_Daze&amp;action=edit">Helios
Final Daze</a>.)</p>
<p><b>Accessibility</b>. Projects should design and test for accessibility compliance, 
following established guidelines and Eclipse fundamental techniques to achieve 
accessibility. Projects must document their accessibility work and compliance. Ideally this would be 
by using a publicly available checklists, such as
</p>
<ul>
<li><a href="http://www.itic.org/resources/voluntary-product-accessibility-template-vpat/">http://www.itic.org/resources/voluntary-product-accessibility-template-vpat/ </a></li>
<li><a href="http://www.section508.gov/">http://www.section508.gov/</a></li> 
<li><a href="http://www.w3.org/TR/WCAG/">http://www.w3.org/TR/WCAG/</a></li>
</ul>
<p>
but, given the <a href="http://wiki.eclipse.org/Planning_Council/Cross_Project_Teams/Accessibility">advice of the Accessibility Cross Project Team</a>, for 
this year's Helios Simultaneous Release, 
projects can document their work or compliance as a negative, such as "we did not do any 
accessibility work or testing and 
do not know the degree of our compliance". But its important to document, so adopters know. 
If possible, and appropriate, accessibility testing tools can be leveraged 
such as <a href="http://www.nvda-project.org/">NVDA</a>. 
The main <a href="http://www.eclipse.org/articles/article.php?file=Article-Accessibility351/index.html">accessibility article at Eclipse Corner</a> 
has been made current (thanks goes to Todd Creasey).
</p>

<p><i>[New this year.]</i>. <b>Unit Tests</b>. Projects must have
some unit tests that can verify at least basic functionality of a build
or distribution. The steps to build and run the tests must be documented
and executable by others.</p>
<p><i>[New this year.]</i>. <b>API Policy</b> Defined and
Documented. Typically would include how 'APIs' are distinguished from
non-API and 'provisional' API, if any. It is recommended that non-API be
marked with x-internal in the bundles manifest. Also, should include
what the commitment is to API, how long maintained after deprecated,
etc. As one example, see <a
       href="http://wiki.eclipse.org/WTP_API_Policy">WTP API Policy</a>.</p>

<p><i>[New this year.]. </i><b>Retention Policy.</b> Projects should
define and document their retention policy. This should include both zip
distributions and repositories. For examples, see <a
       href="http://wiki.eclipse.org/WTP/Retention_Policy">WTP Retention
Policy</a> and <a
       href="http://wiki.eclipse.org/Eclipse_Project_Update_Sites">Eclipse
Project Update Sites</a></p>
<p><i>[New this year.]. </i><b>Project Metrics.</b> Projects should
provide some summary metrics, such as number of bundles, number of
committers, lines of code, number of bugs opened and fixed. This is so
some statements can be made and tracked year-to-year about the size of
the simultaneous release.</p>
<p></p>
<h1>Additional Information</h1>
<h2><a name="pcExceptionProcess">Planning Council Exception
Process</a></h2>
<p><i>[New this year.]</i> Exceptions for any rule or schedule can
be made if there are good enough reasons to. This same exception process
will be followed for things like &quot;requests to respin&quot; a build after a deadline. The
process to get any exception must be open and well documented and follow these
steps:</p>
<p>First, the Project's PMC must approve the request for an
exception and it is the PMC (not the Project) that makes the request to
the Planning Council. The Planning Council member that represents the PMC would
bring the issue forward to the Planning Council.</p>
<p>Second, the exception requires at least 3 positive votes from
active Planning Council members and no negative votes. When time is a
factor (e.g. requests for rebuilds) the deadline for voicing a negative
vote is basically by the time 3 votes are documented. But when time is
not a factor, such as when requesting an exception to one of the
criteria, then a period of one week will pass before being final, to
allow times for concerns or negative votes to be voiced even after 3 positive votes. If
there are not enough positive votes within one week, then the request
for exception will be considered 'failed'. Note that &quot;3&quot; was
chosen under the assumption that the Planning Council member
representing the PMC would vote for it (since that PMC must approve it
initially) so that means 2 others must also vote for it, for 3 total.</p>
<p>Depending on the timing, the issue and votes will be documented
in either the Planning Council Meeting minutes, or on the Planning
Council mailing list. If possible, some automatation may be added to the release reporting tool to aid 
this documentation.</p>

</body>
</html>