<?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 1, 2010<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>Note that as of Juno, around October, 2011, this document was moved to the
Eclipse wiki. For latest content, please 
find at <a href="http://wiki.eclipse.org/SimRel/Simultaneous_Release_Requirements">Eclipse Simultaneious Release Requirements</a>.</p>


<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><b>Joining implies continuous participation. </b> After a
release, there are two follow on activities that must be planned for.
First is that releases maintenance stream. The second is the subquent
year's release. In both cases, it is (as always) up to the project to
decide what to fix or what to enhance, but being part of the train
implies you will always be able to build, in maintenance and in the
subsequent release's milestone builds. Sometimes this means simply
leaving repositories intact, etc., but occasionally projects may need to
fix "prereqs" or similar. 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.
Once in, if projects decide to not be part of future simultaneious
releases, they need to communicate that widely, and as early as
possible, since could effect adopters or downstream projects.</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. May be in the form of providing a URL 
to the checklist, ideally as part of the normal docuware. 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.</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 there are technical reasons not to do so. 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. Exceptions to these principles should be
documented by the project, so we can learn the reasons and extent of
unjarred bundles.</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/Indigo/Contributing_to_Indigo_Build">current
process</a> may be modified throughout the year, if improvements can be
made. Clarification on 03/31/2010: Note that a project's
repositories must contain original (conditioned) jars, and pack.gz files (where
original jar means the jar produced by the build, but which has been
conditioned for pack200). Clarification on 11/08/2010: feature
&quot;includes&quot; must be strict, that is &quot;include&quot; an
exact version of that other feature. This is required so installs and
builds can be repeatable independent of the exact day of the install or
the exact repos enabled. This is the way things are, and have been for years, 
and this statement is just making it explicit. 
While there may, in the future, be new
mechanisms that allow some &quot;line up collection&quot; to be
specified, it will be something new, not the feature
&quot;includes&quot; element.</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 projects participating in Simultaneous Release, 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><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. That is, substantial differences are fine, if required, but we need to avoid minor differences based on case, 
arbitrary dates, and formatting.  Note that the Eclipse Foundation's license or user
agreement files may change from year to year (such as, see <a
	href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=316152">bug
316152</a>) but ideally in Indigo and future releases, it will be easier to
point to a &quot;symbolic&quot; representation of the license, so it
will be accurate with less manual updates from each project (see <a
	href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=306818">bug
306818</a>).</p>

<p><b>Support Primary Eclipse Platform to be in EPP Package.</b> For
Indigo, that means EPP packages (and the features and bundles that go
into them) must be built on and tested with Eclipse 3.7.</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>Capabilities</b>. Each project should provide basic
capability/activity definitions to allow for their UI contributions to
be hidden. These can be provided in a separate plugins and feature to
facilitate inclusion and reuse by consumers, or ... as most projects do
... simply document some examples, so adopters can create their own, or
reuse via copy/paste. Ideally, projects should also provide triggers to
facilitate progressive discovery of functionality (but, not many do,
other than the Platform). As with other &quot;good citizen&quot; items,
projects are free to document &quot;we don't do this&quot; ... but, then
at least it is known and better communicated.</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/indigoPlan/index.php?title=Indigo/Final_Daze&amp;action=edit">Indigo
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
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><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><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><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><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><b>Specify in Plans, support for auxiliary, or future Eclipse
Platforms.</b> For Indigo, this means that each project needs to have a
section (or theme) in their plans (and, that's the standard format
plan), on how they intend to support Eclipse 4.1. The ideal statement
would be to the effect that the project will run and has been tested on
4.1. And, projects that exploit anything specific to 4.1 should explain
that too. Naturally, since each project has their own plans and
priorities, and one possibility is to plan "no support, no testing on
4.1". The purpose of this requirement is to be clear on your plans and
communicate those to the community.</p>

<p></p>
<h1>Additional Information</h1>
<h2><a name="pcExceptionProcess">Planning Council Exception
Process</a></h2>
<p>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>