Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SimRel/Simultaneous Release Requirements"

(→‎Unit Tests)
(136 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 
= The Eclipse Simultaneous Release Requirements  =
 
= The Eclipse Simultaneous Release Requirements  =
  
−
Updated October 3, 2011
+
Updated September 8, 2016
  
 
Authored and maintained by the [[Planning Council|Eclipse Planning Council]]  
 
Authored and maintained by the [[Planning Council|Eclipse Planning Council]]  
  
−
Contact: [mailto:david.williams@us.ibm.com David Williams]  
+
Contact: [mailto:david.williams@acm.org David Williams]  
  
 
This document defines the rules and criteria for participating in the yearly Simultaneous Release. There are more criteria than when releasing at other times. There are more requirements partially because there are more projects releasing at once, so the workload needs to streamlined and made uniform. But also, 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.  
 
This document defines the rules and criteria for participating in the yearly Simultaneous Release. There are more criteria than when releasing at other times. There are more requirements partially because there are more projects releasing at once, so the workload needs to streamlined and made uniform. But also, 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.  
  
−
The spirit of this document is not be so much as a "contract" of what has to be done to release, but instead a statement of what minimally is necessary to make the Yearly Release good, if not great! While each Project does their individual things to make the Release great, this document describes how we, as a group, do that by our voluntary agreement to participate and provide the minimum requirements. We are always open to better documentation and more meaningful agreements, so please feel to make suggestions on how to make our yearly release better from year to year (preferably through your Planning Council representative). Changes may be made to this document throughout the development cycle for clarity or to improve reference links, but nothing new will be added after M4 (that is, things that would effect workload).  
+
The spirit of this document is not be so much as a "contract" of what has to be done to release, but instead a statement of what minimally is necessary to make the Yearly Release good, if not great! While each Project does their individual things to make the Release great, this document describes how we, as a group, do that by our voluntary agreement to participate and provide these minimum requirements. We are always open to better documentation and more meaningful agreements, so please feel to make suggestions on how to make our yearly release better from year to year (preferably through your Planning Council representative). Changes may be made to this document throughout the development cycle for clarity or to improve reference links, but nothing new will be added after M4 (that is, things that would affect workload) so please plan accordingly for the extra work.  
  
−
To allow for some flexibility, exceptions to these requirements are allowed, but to provide balance and foster good communication, any exceptions to the criteria or deadlines must follow the [[#Planning_Council_Exception_Process| Planning Council Exception Process]].  
+
To allow for some flexibility for special cases, exceptions to these requirements are allowed, but to provide balance and foster good communication, any exceptions to the items or deadlines must follow the [[SimRel/Simultaneous_Release_Requirements/Appendix#Planning_Council_Exception_Process | Planning Council Exception Process]].  
  
 
The requirements are divided into three categories:  
 
The requirements are divided into three categories:  
 +
# Mandatory requirements in order to participate in the yearly release. Some of those are required to be completed '''early in the release cycle'''.
 +
# Mandatory requirements to be part of the common software repository and, consequently, the minimum requirements to be part of an EPP package.
 +
# Optional requirements that improve adoption and demonstrate good Eclipse Citizenship, following "the Eclipse Way". These are requirements you do not have to fulfill, but are recommended, encouraged, and the thing that you do have to do is to document if and how you do them.
  
−
#The minimum requirements to be released as part of the "yearly release" ... that is, to able to "claim" you were part of the yearly release . These are the normal release requirements, but done earlier than usual.
+
== Mandatory Requirements for Participation ==
−
#The "must do" requirements to be part of the common software repository and, consequently, the minimum requirements to be part of an EPP package.
+
−
#Requirements to demonstrate good Eclipse Citizenship, following "the Eclipse Way". These are requirements you do not '''have''' to do, but they are recommended, encouraged, and the thing that you do "have" to do is to document if and how you do them.
+
  
−
== Normal release requirements ... but need to do earlier than than usual ==
+
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.
−
 
+
Some of those are required to be completed '''earliy in the release cycle'''.
−
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.  
+
  
 
=== State intent early (M4) ===
 
=== State intent early (M4) ===
  
−
To join a Simultaneous Release, Projects must have stated their intent to do so by M4, at the latest. The "statement of intent" is done formally by marking the "Simultaneous Release Flag" in the project's Portal meta-data. For a normal release, a month's notice is typical, but we ask for more advanced planning for the yearly release.  
+
How to announce your participation. To join a Simultaneous Release, Projects must have stated their intent to do so by M4, at the latest. The "statement of intent" is done by formally announcing participation on the [https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev cross-projects-issues-dev mailing list] ([mailto:emo@eclipse.org EMO] will update the participation page; such as, see the [https://projects.eclipse.org/releases/neon Neon participation page] or [https://projects.eclipse.org/releases/oxygen Oxygen participation page]). Projects are expected to have a [https://www.eclipse.org/projects/handbook/#pmi-releases release record] completed that includes (at least tentative) plan information prior to announcing their intent to participate. The announcement must include the name of the project, a link to the release record, and the offset (+0, +1, +2 or +3, for more information about offsets, see the [[Oxygen/Simultaneous_Release_Plan#Milestones_and_Release_Candidates | Oxygen Simultaneous Release Plan]]). And remember, M4 is the latest to state intent, please do so as early as possible.  For example dates, see the [[Oxygen/Simultaneous_Release_Plan#Schedule | Oxygen Schedule]].
  
−
=== Formal plans, early  (M4) ===
+
If you have any questions, please contact your PMC's Planning Council Representative, or the [mailto:emo@eclipse.org EMO].
  
−
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: by M4 at the latest. Naturally, plans will change as development continues, and we encourage teams to update them periodically, such as every milestone, to reflect reality and progress, but an initial version is required by at least M4 and the final version, due by the release in June, should be a clear statement of what was planned, what was achieved, and what was deffered.
+
=== Formal (standard format) plans, early (M4) ===
  
−
=== IP Documentation  (approximately RC2) ===
+
All projects must have their project plan in the Eclipse Foundation standard format (i.e. create a [https://www.eclipse.org/projects/handbook/#pmi-releases release record] in the PMI for your project and add corresponding milestones in Bugzilla). Committing to be in the Simultaneous Release means you commit to having these plans available early: by M4 at the latest. Naturally, plans will change as development continues, and we encourage teams to update them periodically, such as every milestone, to reflect reality and progress, but an initial version is required by at least M4 and the final version, due by the release in June, should be a clear statement of what was planned, what was achieved, and what was deffered. Every plan, for any release, should have some specific items covered, such as ''Target Environments'' and ''Compatibility with Previous Releases'' but we give some specific guidance here since these are so important to adoption. In addition, we do ask for one extra "theme" item,
 +
that is technically required only for the Simultaneous Release. What you plan, is up to each project, we just want to be sure its clear for adopters and downstream projects.
  
−
Projects must have their IP Logs approved (a normal Eclipse requirement) and will follow the Eclipse Legal deadlines to do so. The IP log deadline is typically RC2.
+
==== Target Environments ====
  
−
Projects are encouraged to created drafts of the Projects IP Logs even earlier. The development process requires the IP Log to always be accurate, but experience shows there often are not, until examined for a release, and there are typically many issues to resolve, or fixed, before the final submission to the IP staff. For example, sometimes a CQ might have the wrong flag, and cause it to not show up in the Auto IP Log, or perhaps a common, already approved 3rd party jar was was used, but no CQ for that specific project entered. The purpose of having these early drafts is so that projects get familiar with what is required, and do not allow work to build up at the end, since that could cause a "bottleneck" at a critical time and jeopardize having the ability to resolve all issues in time to be released. Also, some adopters will want to look at early drafts to see what 3rd party requirements are associated with the code they are planning to adopt.  
+
Exactly what platforms and runtimes a project supports is up to them and their community, but it is required all projects document what platforms they support, especially if they have native (non-Java) code and especially if it is
 +
different than the [http://www.eclipse.org/projects/project-plan.php?projectid=eclipse#target_environments set of platforms supported by the Eclipse Platform itself].
  
−
A good guideline is to have a draft of your IP Log by M5, and plan for it to be complete for M7.
+
For additional information see - [[SimRel/Simultaneous_Release_Requirements/Appendix#Target_Environments | Appendix: Target Environments]]
  
−
Note that being in the Simultaneous Release will give your IP CQ requests 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. But, there is a deadline for CQs for the yearly release, usually in February, near M5, to have all required CQs submitted, on file (but not necessarily approved by then).
+
==== Compatibility with Previous Releases ====
  
−
=== Release Review (approximately RC3) ===
+
It should be part of every project's plan to have a section detailing compatibility with previous releases. This should not only include commitments to API and binary compatibility, but ideally would also include plans for source compatibility, workspace compatibility, and project "coexistence" compatibility. See the template in [[Development_Resources/Project_Plan| standard plan reference]] and for examples, see the plans for the [http://www.eclipse.org/projects/project-plan.php?projectid=eclipse#compatibility| Eclipse Platform] and the [http://www.eclipse.org/projects/project-plan.php?projectid=webtools#compatibility| Web Tools Platform project].
  
−
The release review archival materials must be complete by the date specified by the EMO, which is earlier than it would be for other releases. (Typically around RC3.)
+
For additional information see - [[SimRel/Simultaneous_Release_Requirements/Appendix#Compatibility_with_Previous_Releases | Appendix: Compatibility]]
  
−
A Project's PMC must approve the projects request for review (a normal Eclipse requirement). It is recommended, to help organize and streamline the yearly Simultaneous release, that a PMC 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 page). The short summary can be documented in a mailing list, PMC Meeting notes, or even a wiki document.
+
=== IP Documentation and Logs (RC1) ===
  
−
== More is required to be in common repository  ==
+
Projects must have their IP logs approved (a normal Eclipse requirement) but follow the earlier deadlines set by EMO and IP staff. The IP log deadline is typically mid-week RC1.
  
−
The requirements in this section must be met for a project to be on the common, central repository (e.g. /releases/juno) for end users to discover easily and therefore are the 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.  
+
For additional information see - [[SimRel/Simultaneous_Release_Requirements/Appendix#IP_Documentation_and_Logs_.28RC1.29 | Appendix: IP Logs]]
 +
 
 +
=== Release Review and compliance to requirements documentation (RC3) ===
 +
 
 +
The release review documentation must be complete by the date specified by the EMO, which is earlier than it would be for other releases. (Typically mid-week during RC3.) In addition to normal release plan requirements, for a Simultaneous Release, Project Leads must document their verification that the project complies with all extra requirements of this Simultaneous Release document, as they apply to their project, and document any exceptions, there in the release review documentation. This is intended to be a few short sentences or paragraphs, not a detailed checklist.
 +
 
 +
For additional information see - [[SimRel/Simultaneous_Release_Requirements/Appendix#Release_Review_and_compliance_to_requirements_documentation_.28RC3.29 | Appendix: Release Review]]
 +
 
 +
== Mandatory Requirements for the Simultaneous Repository and EPP ==
 +
 
 +
The requirements in this section were historically called "the must do" items -- they are a "must" not for the release, but must be met for a project to be on the common, central repository (e.g. /releases/oxygen). The common repo is for end users to discover easily and therefore (per EPP Policy) are the 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 and can be installed 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.  
  
 
=== Integrate Early and Often ===
 
=== Integrate Early and Often ===
  
−
First-time participants are expected to be in an aggregation build by M4, at the latest. Then, once in, always in. This firstly and mostly means by agreeing to be in the yearly release, in June, you will also participate in the two planned Service Releases. But, even more than that, it is assumed that once you are in one Simultaneous Release, you will continue to be, so the following year, it is assumed you will be in M1 ... that is, you should not wait until M4 every year, even though that is the deadline for first-timers.  
+
First-time participants are expected to be in an aggregation build by M4, at the latest. Then, once in, always in. This firstly means by agreeing to be in the yearly release, in June, you will also participate in the planned Simultaneous Update Releases. But, even more than that, it is assumed that once you are in one Simultaneous Release, you will continue to be, so the following year, it is assumed you will be in M1 ... that is, you should not wait until M4 every year, even though that is the deadline for first-timers.  
 +
 
 +
[added 09/2016] '''Note: ''' There is an implicit "opt-in" assumed when we start a new development stream. That is, projects will be left enabled when we start a new stream. But if projects appear to not be active, the Planning Council will first try to contact the Project and their PMC. If no response and no release record in place by M4, then they will be disabled or removed for M5.
 +
 
 
Put another way, being
 
Put another way, being
 
part of the Simultaneous Release is not a "one time"
 
part of the Simultaneous Release is not a "one time"
 
activity, covering only the release part of the development cycle.  
 
activity, covering only the release part of the development cycle.  
−
Instead it is a commitment to stay
+
Instead, it is a commitment to stay
 
"simultaneous" on an on-going basis. Once in, if a project
 
"simultaneous" on an on-going basis. Once in, if a project
 
decides to not be part of future simultaneous releases, they need
 
decides to not be part of future simultaneous releases, they need
 
to communicate that widely, and as early as possible, since could
 
to communicate that widely, and as early as possible, since could
−
effect adopters or downstream projects.
+
affect adopters or downstream projects.
 +
 
 +
[added 12/2015, for Neon] While part of the mechanics of [[Simrel/Contributing_to_Simrel_Aggregation_Build#The_best_format_and_process_for_contributing_to_Sim._Release| contributing to the build]], it is required that any contribution to the Simultaneous Release repository be done by a unique change to the b3aggrcon file. There are two ways to do this. First, your contribution repository can point to a simple repository where you know for sure there is only one version of your contribution available. Second, your contribution repository can be a composite repository but then you name exactly which versions to include. That is you need to specify all 4 version fields. You can, of course, do both methods, simple repository and name exact versions if you want the safety of that redundancy.
  
 
=== Communication  ===
 
=== Communication  ===
  
−
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.  
+
At least one person from each project in a Simultaneous Release must subscribe to [https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev 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 (add cross-project.inbox@eclipse.org to the "Add users to my watch list" box at the bottom of your [https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email Bugzilla email preferences] page), 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.  
  
−
Your representative to the Planning Council, either from PMC or Strategic Member, must attend Planning Council 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.  
+
Your representative to the Planning Council, either from PMC or Strategic Member, must attend Planning Council 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 issues that affect 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.  
  
−
Build-team members (or their designated alternates) from each project may be asked to provide direct communication channels: at least email (if not phone, IM, IRC) and at least one build team member must be "on call" during the integration periods.  
+
A build-team member or release engineer from each project must be "on call" during the aggregation or integration periods to make sure any issues can be addresses quickly.
  
−
=== API  ===
+
=== Required Bundle forms and formats ===
  
−
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.
+
==== Version Numbering ([[#Testing_of_Simultaneous_Release_Repository|tested]])  ====
  
−
=== Message Bundles  ===
+
Projects must use 4-part version numbers following the common semantics described in the [[Version Numbering|Eclipse version numbering]] document.
  
−
Projects must use [http://help.eclipse.org/indigo/topic/org.eclipse.platform.doc.isv/reference/misc/message_bundles.html Eclipse message bundles] unless there are technical reasons not to, since these are known to be more memory efficient that some other forms of handling UI-releated strings.
+
==== OSGi bundle format  ====
  
−
=== Version Numbering ([[#Testing_of_Common_Repository|tested]]) ===
+
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 {{bug|130598}}.)  
  
−
Projects must use 4-part [[Version Numbering|version numbers]].
+
==== Execution Environment ([[#Testing_of_Simultaneous_Release_Repository|tested]]) ====
  
−
=== OSGi bundle format  ===
+
All plug-ins (that contain Java code) must correctly specify their [[Execution Environments|Bundle Required Execution Environment (BREE)]]. Resource-only bundles do not need a BREE since it doesn't matter which version of Java they are used with.
  
−
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 {{bug|130598}}.)  
+
==== Signing ([[#Testing_of_Simultaneous_Release_Repository|tested]]) ====
  
−
=== Execution Environment ([[#Testing_of_Common_Repository|tested]])===
+
Projects must use [[JAR Signing|signed plugins and features using the Eclipse certificate]].
  
−
All plug-ins (that contain Java code) must correctly specify their [[Execution Environments|Bundle Required Execution Environment (BREE)]].
+
[added 12/2015, for Neon]. Note: If a jar is already signed by the Eclipse certificate, then it must not be re-signed by projects for the release train.
  
−
=== Signing ([[#Testing_of_Common_Repository|tested]])===
+
==== Jarred Bundles  ====
  
−
Projects must use [[JAR Signing|signed plugins using the Eclipse certificate]].
+
Projects must use jarred plug-ins (with unpack=false) unless there are technical reasons not to (i.e. require the directory form).  
  
−
=== Jarred Bundles  ===
+
==== License text consistency ([[#Testing_of_Simultaneous_Release_Repository|tested]]) ====
  
−
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.  
+
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 [http://www.eclipse.org/legal/epl/about.php Eclipse Foundation "about" template], 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, dates, and formatting. Note that the Eclipse Foundation's license or user agreement files may change from year to year (such as, see {{bug|316152}} but since Indigo, it will be easier to point to a "symbolic" representation of the license, that is inserted at build time, so it will be accurate with less manual updates from each project (see {{bug|306818}}).
  
−
=== Re-use and share common third party code (partially [[#Testing_of_Common_Repository|tested]])===
+
=== Re-use and share common third party code (partially [[#Testing_of_Simultaneous_Release_Repository|tested]])===
  
−
Any third-party plug-ins that are common between projects must be consumed via [http://www.eclipse.org/orbit Orbit]. The Simultaneous Release must not have duplicate third-party libraries (note that this only applies to versions of the libraries; thus if project A requires foo.jar 1.6 and project B uses foo.jar 1.7, that's normally ok, different service versions a little less ok, such as 1.7.1 vs 1.7.2 (those should be explained, if required), and a qualifier-only difference is definitely not ok).
+
Any third-party plug-ins that are common between projects must be consumed via [http://www.eclipse.org/orbit/ Orbit]. The Simultaneous Release must not have duplicate third-party libraries (note that this only applies to versions of the libraries; thus if project A requires foo.jar 1.6 and project B uses foo.jar 1.7, that's normally ok, different service versions a little less ok, such as 1.7.1 vs 1.7.2 (those should be explained, if required), and a qualifier-only difference is definitely not ok).
  
−
Note: the "partially tested", for this case, means there is a report of "Non Unique Versions used in repository" which can catch issues of not using common bundles. See [http://build.eclipse.org/juno/simrel/reports/nonUniqueVersions.txt current report] for an example.
+
Note: the "partially tested", for this case, means there is a report of "Non Unique Versions used in repository" which can catch issues of not using common bundles. See [http://build.eclipse.org/simrel/kepler/reporeports/reports/nonUniqueVersions.txt current report] for an example.
  
−
=== Optimization ([[#Testing_of_Common_Repository|tested]])===
+
=== Provide optimized p2 repository ([[#Testing_of_Simultaneous_Release_Repository|partially tested]]) ===
  
−
Projects must [http://help.eclipse.org/indigo/topic/org.eclipse.platform.doc.isv/guide/p2_repositorytasks.htm optimize their p2 repositories] to reduce bandwidth utilization and provide a better install and update experience for users.
+
Projects must provide their own project p2 repository for their own project and updates. Projects must [http://help.eclipse.org/juno/topic/org.eclipse.platform.doc.isv/guide/p2_repositorytasks.htm optimize their p2 repositories] to reduce bandwidth utilization and provide a better install and update experience for users.
  
−
=== Provide p2 repository ===
+
In addition, they must provide their artifacts 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 [[Simrel/Contributing_to_Simrel_Aggregation_Build|current process]] may be modified throughout the year, if improvements can be made.
  
−
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 [[Juno/Contributing to Juno Build|current process]] 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 "includes" must be strict, that is "include" 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 "line up collection" to be specified, it will be something new, not the feature "includes" element.  
+
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). This is mentioned since in some scenarios, only the pack.gz files needs to be left there ... but, that practice is controversial so for now we ask for both ... as one example, there are problems with Java 7 unpacking pack.gz files with nested jars ({{bug|361628}}).  
  
−
=== Support Translations  ===
+
Feature "includes" must be strict, that is "include" 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 since technically it is possible for people to use some p2 publishers that don't have this predictability or repeatability (which can certainly be appropriate in some contexts, just not the Simultaneous Release repository). While there may, in the future, be new mechanisms that allow some "line up collection" to be specified, it will be something new, not changing the meaning of feature "includes" element via p2 metadata.
  
−
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 "keep up" with late changes).  
+
For similar reasons, the repositories produced and contributed must use p2 publishers that produce greedy='false' in the content metadata for runtime-optional dependencies. See {{bug|247099}} and the [http://wiki.eclipse.org/Equinox/p2/Publisher p2 Publisher wiki] for some history and details on this issue of greedy vs. non-greedy requirements. But in brief, to have a runtime-optional dependency be non-greedy is important for several reasons, especially in an IDE environment. First it gives ultimate control over what is installed to the user, based on their feature selection, instead of depending on what happens to be available from the repositories they are pointing to at that moment it time. It also makes it much easier for adopters to be able to predict (and maintain) what their users have installed. In fact, if something is runtime-optional, but pulled into an install because someone did not specify greedy='false' meta-data, there is no way an adopter can provide a patch feature to one of their customers if that optional bundle causes a bug.
  
−
=== Excel in NL support  ===
+
Everyone's p2 repositories must make use the of p2.mirrorsURL property. For "how to" information, see [[Equinox/p2/p2.mirrorsURL|p2.mirrorsURL wiki]]. Note: this is not really a "Simultaneous Release Requirement" but is required of any p2 repository on Eclipse Foundation infrastructure, and is just documented here to help spread the word and educate newcomers.
  
−
The Project must use [[ICU4J]], where appropriate, to excel in NL support. (The latest ICU4J bundles will be in Orbit).  
+
Similar to p2.mirrorsURL attribute, a well behaved, well optimized p2 repository should contain a p2.index file. This is especially important for "composite repos" and prevents unnecessary "round trips" to server looking for files. See {{bug|347448}} for history and for how-to instructions, see the [[Equinox/p2/p2_index| p2 wiki]]. Again, this is not so much a "Simultaneous Release Requirement" but is recommended of any p2 repository on Eclipse Foundation infrastructure, and is just documented here to help spread the word and educate newcomers.
  
 
=== Branding  ===
 
=== Branding  ===
  
−
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.  
+
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 should contribute to the welcome page when appropriate.
  
 
=== Do No Harm  ===
 
=== Do No Harm  ===
  
−
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.
+
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 installed independently. If such a problem is identified, the affected projects must track down and fix the problem, to be in the simultaneous release repository.
  
−
=== License text consistency ([[#Testing_of_Common_Repository|tested]])===
+
=== Document Yearly Update Policy  ===
  
−
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 [http://www.eclipse.org/legal/epl/about.php Eclipse Foundation "about" template], 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, dates, and formatting. Note that the Eclipse Foundation's license or user agreement files may change from year to year (such as, see {{bug|316152}} but ideally in Indigo and future releases, it will be easier to point to a "symbolic" representation of the license, so it will be accurate with less manual updates from each project (see {{bug|306818}}).
+
It is required that participating projects document whether or not they support updating from one yearly release to the next. For example, from Neon (2016) to Oxygen (2017). [The current implementation plan for tracking, details TBD (see {{bug|509251}}), is for there to be a field in the PMI Release Record that must be checked "Yes" or "No".] To meet this requirement in the affirmative:
 +
:-  The project will accept bugs as valid if an update does not work, or there is a functional problem after updating.
 +
:- The project will test such updates.
 +
:- The project will document, such as in a "Migration Guide" or "Release Notes", any details about what does or does not work across yearly updates. For example, a user's workspace may be "migrated" to the new release and not be usable by the old release after the update (but projects freshly checked out or imported would continue to work with either). Or, perhaps there are some known cases where some preference setting would be lost and have to be set again by the user.  
  
−
=== Support Primary Eclipse Platform to be in EPP Package. ===
+
Please note, this requirement is about ''documenting'' a project's policy. As of this writing (for Oxygen) it is possible for a project to simply document "No, updates from previous releases are not supported". In the future, after more experience is gained, it is anticipated that it will be required to support "continuous updates" even across yearly boundaries. The only reason we do not make it required at this point in time is that we are not sure we understand all the implications. Accordingly, {{bug|509237}} has been opened to document "requirements or issues" that participating projects are aware of or find in support of this effort.
  
−
For Juno, that means EPP packages (and the features and bundles that go into them) must be built on and tested with Eclipse 4.2.
+
Also note, it is a given and documented elsewhere that "update releases" must be supported, such as updating from Neon to Neon.1, etc.
  
−
== Required for good adoption (but, optional)  ==
+
== Optional Requirements ==
  
−
Projects should exhibit good Eclipse Citizenship, to Release and participate in Common Discovery Site and EPP Packages. These are often "best practices" 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.  
+
The items in this category are, in a sense, optional. That is, what, exactly, is done by a project is optional, but
 +
it is required for projects to '''document''' what they do. These are often "best practices" that many projects have found essential at driving good adoption, plus the items sometimes speak to the quality of the project (quality as an Eclipse "good citizen", as opposed to their code quality or architecture). But, their importance is not as universally relevant to all projects and their adopters, hence it is only required that each project document what they do for these items, but exactly what they do is up to the best judgment of the project and their community.  
  
−
=== Engage Community  ===
+
Please see the appendix for a detailed list of these items: [[SimRel/Simultaneous_Release_Requirements/Appendix#Required_for_good_adoption | Appendix: Required for good adoption]]
−
 
+
−
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 [[Architecture Council/New and Noteworthy|New & Noteworthy]] 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 & noteworthy should be linked in to the collective New & Noteworthy.
+
−
 
+
−
=== Usability  ===
+
−
 
+
−
Should follow the [[User Interface Guidelines|User Interface Guidelines]]. The [[UI Checklist|UI Checklist]] is a good place to start. Also, when possible, it is good to have a [[UIBPWG UI Walkthrough|UI walkthrough]].
+
−
 
+
−
=== Performance  ===
+
−
 
+
−
Project should have measurable performance criteria that are regularly tested against. Projects should devote at least one milestone to performance and scalability improvements.
+
−
 
+
−
=== Test Localization  ===
+
−
 
+
−
The project should use the Babel Pseudo Translation Test to verify their translatability. See {{bug|217339}} [Need better reference link.]
+
−
 
+
−
=== Capabilities  ===
+
−
 
+
−
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 "good citizen" items, projects are free to document "we don't do this" ... but, then at least it is known and better communicated.
+
−
 
+
−
=== Enable Use with All Languages  ===
+
−
 
+
−
Should design and test for enabling all languages including bidi, unicode characters, etc. This is different than "translating" the software. For example, while using an English version of Eclipse Web Tools Platform, someone should be able to create a Chinese language web application. [Need "how to" reference link.]
+
−
 
+
−
=== Builds  ===
+
−
 
+
−
Projects must have a mature, stable build process: documented, scripted, repeatable, and executable by others on their own system. Ideally there would be just a few commands to run from a Linux shell to accomplish the build, but there might need to be a page of "set up" instructions of what's required (e.g. if CVS or GIT needs to be installed, certain version of Java, etc.) Of course, there may be some parts of it that do not work completely (such as, being signed by the Eclipse code certificate would typically not work when ran by others, on their own system) but the build should not fail if it does not sign, and otherwise should produce essentially the same functional output as the "official build". Note, this build should include both producing the code and producing the unit tests. 
+
−
 
+
−
[Added 10/18/2011] Also, projects should provide a "source build" or some instructions on how to get all the literal source that goes into a particular build or release. This is different than producing "source jars" during the build. The "source jars" are simply Java code that can be used in the IDE, such as for JavaDoc or debugging. A "source build" would certainly include the Java code, but also any additional source required to build the code, such as various property files, perhaps model or grammar specifications that are converted to Java during the build, the source that goes into producing native DLLs, etc. The "source build" can serve two functions: allows building the project "from scratch", (not from the source code repository) and second an adopter might want to have the literal source to check or investigate IP issues. You can provide the literal "source" that could be used for a source build, but most projects would simply provide instructions on "how to fetch" all the source that went into a particular build. See {{bug|185146}} for the origin of this "source build" request.
+
−
 
+
−
 
+
−
=== Unit Tests ===
+
−
 
+
−
Projects should have unit tests with enough documented instructions that others (adopters or extenders) can run, independently of the build, in their own environments. Ideally with just a few commands, but as with builds, might require a description of machine set-up.
+
−
 
+
−
=== Ramp Down Planned and Defined  ===
+
−
 
+
−
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 [http://www.eclipse.org/eclipse/development/freeze_plan_3.5.php Platform 3.5 Endgame plan] as a guideline. See also [[Indigo/Final Daze|Indigo Final Daze]].)
+
−
 
+
−
=== Accessibility  ===
+
−
 
+
−
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
+
−
 
+
−
*[http://www.itic.org/resources/voluntary-product-accessibility-template-vpat/ http://www.itic.org/resources/voluntary-product-accessibility-template-vpat/]
+
−
*[http://www.section508.gov/ http://www.section508.gov/]
+
−
*[http://www.w3.org/TR/WCAG/ http://www.w3.org/TR/WCAG/]
+
−
 
+
−
but, given the [[Planning Council/Cross Project Teams/Accessibility|advice of the Accessibility Cross Project Team]], 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 [http://www.nvda-project.org/ NVDA]. The main [http://www.eclipse.org/articles/article.php?file=Article-Accessibility351/index.html accessibility article at Eclipse Corner] has been made current (thanks goes to Todd Creasey).
+
−
 
+
−
[TODO: These entry seems out of date. I recall we used to have some "example templates" that projects could fill out regarding specific areas of compliance/testing ... I need to find those and update this entry].
+
−
 
+
−
=== Unit Tests  ===
+
−
 
+
−
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.
+
−
 
+
−
=== API Policy  ===
+
−
 
+
−
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 [[WTP API Policy|WTP API Policy]].
+
−
 
+
−
=== Retention Policy  ===
+
−
 
+
−
Projects should define and document their retention policy. This should include both zip distributions and repositories. For examples, see [[WTP/Retention Policy|WTP Retention Policy]] and [[Eclipse Project Update Sites|Eclipse Project Update Sites]].
+
−
 
+
−
=== Project Metrics  ===
+
−
 
+
−
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.
+
−
 
+
−
=== Target Environments ===
+
−
 
+
−
[added 10/18/2011]
+
−
 
+
−
We do not have any "requirement" of what platforms or Operating Systems projects must support, mostly because its never been an issue, but simply encourage all projects to well document what platforms they support, especially if they have native (non-Java) code and especially if it is
+
−
different than the [http://www.eclipse.org/projects/project-plan.php?projectid=eclipse#target_environments set of platforms supported by the Eclipse Platform itself].
+
−
 
+
−
Similarly, we have never found a reason to "require" support of a particular minimum (or, maximum) Java level to use (such as Java 5, Java 6, Java 7). But, the question often gets asked, so we simply clarify here that projects should well document their minimum requirements to run or develop the source code. In general, the advise is to a) use a level that makes life easy for committers, but b) does not negatively impact adopters (such as some "low level" server code might still need to run on 1.4 JREs), and c) does not "force" others on the release train to use a level higher than they would prefer or be able to accommodate (some language constructs, such as enum, can essentially become part of your API, and force others to move up, but others things, such as syntax of for loops, do not effect your API or downstream consumers since should still run and be API compatible with lower levels of Java).
+
−
 
+
−
It would be anticipated that this year, for Juno, many Eclipse users would still be using Java 6, perhaps a few on Java 5, but projects should test extensively on Java 7 since its use will likely grow and become common place by the time Juno ships, especially over Juno's life time. In other words, in general, write your code to the lowest level possible, but test on the highest level possible.
+
−
 
+
−
To satisfy this requirement, please document your supported platforms in your standard project plan by having a section labeled, exactly,
+
−
as <nowiki><target_environments></nowiki>. See template in [http://wiki.eclipse.org/Development_Resources/Project_Plan standard plan reference] and for an example, other than the [http://www.eclipse.org/projects/project-plan.php?projectid=eclipse#target_environments Platform's], see the subject [http://www.eclipse.org/projects/project-plan.php?projectid=webtools#target_environments section in Web Tools plan].
+
−
 
+
−
Be sure to raise any "platform level" questions or issues to the cross-project list.
+
−
 
+
−
=== Compatibility with Previous Releases ===
+
−
 
+
−
[added 11/09/2011]
+
−
 
+
−
It should be part of every project's plan to have a section detailing compatibility with previous releases. This should not only include commitments to API and binary compatibility, but also include plans for source compatibility, workspace compatibility, and project "coexistence" compatibility. See the template in [http://wiki.eclipse.org/Development_Resources/Project_Plan standard plan reference] and for examples, see the plans for the [http://www.eclipse.org/projects/project-plan.php?projectid=eclipse#compatibility| Eclipse Platform] and the [http://www.eclipse.org/projects/project-plan.php?projectid=webtools#compatibility| Web Tools Platform project].
+
−
 
+
−
Note: this primarily applies to projects that have "released before", but even those releasing for the first time should be aware of this issue as there could be things done "now" for future compatibility and migration ... these need to be "thought through" even for your first release, to make sure your second release maintains appropriate compatibility.
+
−
 
+
−
The intent, here, is for projects to document their intent and whether or not bugs about compatibility would be considered valid. For example, a project might document "we support only a one-time migration of projects, and if it is a shared project, all developers must move to new version at the same time". While that's less that ideal, at least then adopters know what to expect and can make their plans based on that information.
+
−
 
+
−
=== Make it easy to get your source from your repository ===
+
−
 
+
−
[added 10/18/2011]
+
−
 
+
−
Projects should make it easy for potential contributers (and adopters) to get your source from your repository (that is, source that exactly "matches" what was used in a build or release). This might be done by producing a [http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Ftasks%2Ftasks-cvs-project-set.htm "team project set"] during your build and making that available from your downloads page. Another excellent way to accomplish this, while maybe not suitable for all projects, is to make your bundle's source repository "self documenting" by using the [http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Ftasks%2Fui_import_from_cvs.htm Eclipse-SourceReference directive] in your manifest.mf file (its very easy to have this added if your build makes use of [http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Freference%2Fpde_builder_config.htm PDE build or its properties]).
+
−
 
+
−
=== Provide archived p2 repositories ===
+
−
 
+
−
[added 10/18/2011]
+
−
 
+
−
While its obviously required to provide p2 repositories for end-users, for easy installation, and for aggregation, it is also very useful to provide a p2 repository from a particular build in the form of a zip file. This allows adopters to get just the unambiguous artifacts from that particular build, to a) do their own builds "off line" and b) be able to archive that zip file as a guaranteed constant prereq for their own future maintenance builds. This '''might''' become a requirement in future Simultaneous Releases, instead of only a "suggestion for good adoption" because
+
−
# it would be a good way for us to have reproducible aggregation builds (currently, the aggregation builds are not guaranteed reproducible because projects might change their repository between runs, thus quietly providing different content to the aggregation build), and
+
−
# it ''might'' become an important component of providing LTS (Long Term Support), allowing maintainers to rebuild some subset of code, and then easily reassemble particular packages, in a reproducible, predictable way.
+
−
So, issues and reports of experiences would be welcome during Juno.
+
−
 
+
−
=== Specify, in Plans, support for auxiliary, or previous Eclipse Platforms  ===
+
−
 
+
−
For Juno, this means that each project needs to have a section (or theme) in their plans (and, to be clear, that is the standard format plan), on how they intend to support Eclipse 3.8. We will have 4.2 as primary (hence the one used for EPP Packages) but ask participating projects to have a clear plan theme item titled, exactly, '''"Support for Eclipse 3.8 workbench"'''. We ask for exact working, to enable the possibility of being able to automatically produce a "summary" of auxiliary support. To be more exact, this should be an item in your <nowiki>"<p:themes_and_priorities>"</nowiki> section, hence you would have an element there named <nowiki>"<p:theme name="Support for Eclipse 3.8 workbench">"</nowiki>.
+
−
 
+
−
Possible topics and descriptions to be covered in your description might be similar to:
+
−
 
+
−
*Not at all. No support for 3.8 based apps.
+
−
*We will accept bugs against 3.8 based apps, but do not test or compile against it.
+
−
*We will compile against and somewhat test 3.8, though 4.2 is primary.
+
−
*We will support 3.8 as well as 4.2, but the exact functionality may differ.
+
−
*We will support 3.8 and 4.2 equally, and the functionality will be the same.
+
−
 
+
−
For an example, see the [http://www.eclipse.org/projects/project-plan.php?projectid=webtools#support38 WTP statement on 3.8 support].
+
  
 
= Additional Information  =
 
= Additional Information  =
  
−
== Planning Council Exception Process ==
+
* [[SimRel/Simultaneous_Release_Requirements/Appendix#Planning_Council_Exception_Process | Planning Council Exception Process]]
−
 
+
* [[SimRel/Simultaneous_Release_Policy_FAQ| Simultaneous Release Policy FAQ]]
−
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 "requests to respin" a build after a deadline. The process to get any exception must be open and well documented and follow these steps:
+
* [[SimRel/Simultaneous_Release_Requirements/Appendix#Testing_of_Simultaneous_Release_Repository | Testing of Simultaneous Release Repository]]
−
 
+
−
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.
+
−
 
+
−
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 "3" 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.
+
−
 
+
−
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 automation may be added to the release reporting tool to aid this documentation.
+
  
−
== Testing of Common Repository ==
+
<br/><br/>
  
−
Some of the items marked "(tested)" means that there is some degree of automatic checking and reporting done on the common repository. The reports, for example, see the [http://build.eclipse.org/juno/simrel/ Juno Reports] do not test "project by project" but as a whole, give some idea of where there are violations or problems. Ideally, the "common repo" tests should be simply a final sanity check, and projects can include their own automatic testing during their own build processes. See [[SimRel/Simultaneous_Release_Reports_FAQ| reporting FAQs]] for more information.
+
[[Category:Juno| ]] [[Category:Kepler| ]] [[Category:Luna| ]] [[Category:Mars| ]] [[Category:Neon| ]] [[Category:Oxygen| ]] [[Category:Photon| ]]

Revision as of 14:05, 12 December 2017

The Eclipse Simultaneous Release Requirements

Updated September 8, 2016

Authored and maintained by the Eclipse Planning Council

Contact: David Williams

This document defines the rules and criteria for participating in the yearly Simultaneous Release. There are more criteria than when releasing at other times. There are more requirements partially because there are more projects releasing at once, so the workload needs to streamlined and made uniform. But also, 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.

The spirit of this document is not be so much as a "contract" of what has to be done to release, but instead a statement of what minimally is necessary to make the Yearly Release good, if not great! While each Project does their individual things to make the Release great, this document describes how we, as a group, do that by our voluntary agreement to participate and provide these minimum requirements. We are always open to better documentation and more meaningful agreements, so please feel to make suggestions on how to make our yearly release better from year to year (preferably through your Planning Council representative). Changes may be made to this document throughout the development cycle for clarity or to improve reference links, but nothing new will be added after M4 (that is, things that would affect workload) so please plan accordingly for the extra work.

To allow for some flexibility for special cases, exceptions to these requirements are allowed, but to provide balance and foster good communication, any exceptions to the items or deadlines must follow the Planning Council Exception Process.

The requirements are divided into three categories:

  1. Mandatory requirements in order to participate in the yearly release. Some of those are required to be completed early in the release cycle.
  2. Mandatory requirements to be part of the common software repository and, consequently, the minimum requirements to be part of an EPP package.
  3. Optional requirements that improve adoption and demonstrate good Eclipse Citizenship, following "the Eclipse Way". These are requirements you do not have to fulfill, but are recommended, encouraged, and the thing that you do have to do is to document if and how you do them.

Mandatory Requirements for Participation

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. Some of those are required to be completed earliy in the release cycle.

State intent early (M4)

How to announce your participation. To join a Simultaneous Release, Projects must have stated their intent to do so by M4, at the latest. The "statement of intent" is done by formally announcing participation on the cross-projects-issues-dev mailing list (EMO will update the participation page; such as, see the Neon participation page or Oxygen participation page). Projects are expected to have a release record completed that includes (at least tentative) plan information prior to announcing their intent to participate. The announcement must include the name of the project, a link to the release record, and the offset (+0, +1, +2 or +3, for more information about offsets, see the Oxygen Simultaneous Release Plan). And remember, M4 is the latest to state intent, please do so as early as possible. For example dates, see the Oxygen Schedule.

If you have any questions, please contact your PMC's Planning Council Representative, or the EMO.

Formal (standard format) plans, early (M4)

All projects must have their project plan in the Eclipse Foundation standard format (i.e. create a release record in the PMI for your project and add corresponding milestones in Bugzilla). Committing to be in the Simultaneous Release means you commit to having these plans available early: by M4 at the latest. Naturally, plans will change as development continues, and we encourage teams to update them periodically, such as every milestone, to reflect reality and progress, but an initial version is required by at least M4 and the final version, due by the release in June, should be a clear statement of what was planned, what was achieved, and what was deffered. Every plan, for any release, should have some specific items covered, such as Target Environments and Compatibility with Previous Releases but we give some specific guidance here since these are so important to adoption. In addition, we do ask for one extra "theme" item, that is technically required only for the Simultaneous Release. What you plan, is up to each project, we just want to be sure its clear for adopters and downstream projects.

Target Environments

Exactly what platforms and runtimes a project supports is up to them and their community, but it is required all projects document what platforms they support, especially if they have native (non-Java) code and especially if it is different than the set of platforms supported by the Eclipse Platform itself.

For additional information see - Appendix: Target Environments

Compatibility with Previous Releases

It should be part of every project's plan to have a section detailing compatibility with previous releases. This should not only include commitments to API and binary compatibility, but ideally would also include plans for source compatibility, workspace compatibility, and project "coexistence" compatibility. See the template in standard plan reference and for examples, see the plans for the Eclipse Platform and the Web Tools Platform project.

For additional information see - Appendix: Compatibility

IP Documentation and Logs (RC1)

Projects must have their IP logs approved (a normal Eclipse requirement) but follow the earlier deadlines set by EMO and IP staff. The IP log deadline is typically mid-week RC1.

For additional information see - Appendix: IP Logs

Release Review and compliance to requirements documentation (RC3)

The release review documentation must be complete by the date specified by the EMO, which is earlier than it would be for other releases. (Typically mid-week during RC3.) In addition to normal release plan requirements, for a Simultaneous Release, Project Leads must document their verification that the project complies with all extra requirements of this Simultaneous Release document, as they apply to their project, and document any exceptions, there in the release review documentation. This is intended to be a few short sentences or paragraphs, not a detailed checklist.

For additional information see - Appendix: Release Review

Mandatory Requirements for the Simultaneous Repository and EPP

The requirements in this section were historically called "the must do" items -- they are a "must" not for the release, but must be met for a project to be on the common, central repository (e.g. /releases/oxygen). The common repo is for end users to discover easily and therefore (per EPP Policy) are the 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 and can be installed 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.

Integrate Early and Often

First-time participants are expected to be in an aggregation build by M4, at the latest. Then, once in, always in. This firstly means by agreeing to be in the yearly release, in June, you will also participate in the planned Simultaneous Update Releases. But, even more than that, it is assumed that once you are in one Simultaneous Release, you will continue to be, so the following year, it is assumed you will be in M1 ... that is, you should not wait until M4 every year, even though that is the deadline for first-timers.

[added 09/2016] Note: There is an implicit "opt-in" assumed when we start a new development stream. That is, projects will be left enabled when we start a new stream. But if projects appear to not be active, the Planning Council will first try to contact the Project and their PMC. If no response and no release record in place by M4, then they will be disabled or removed for M5.

Put another way, being part of the Simultaneous Release is not a "one time" activity, covering only the release part of the development cycle. Instead, it is a commitment to stay "simultaneous" on an on-going basis. Once in, if a project decides to not be part of future simultaneous releases, they need to communicate that widely, and as early as possible, since could affect adopters or downstream projects.

[added 12/2015, for Neon] While part of the mechanics of contributing to the build, it is required that any contribution to the Simultaneous Release repository be done by a unique change to the b3aggrcon file. There are two ways to do this. First, your contribution repository can point to a simple repository where you know for sure there is only one version of your contribution available. Second, your contribution repository can be a composite repository but then you name exactly which versions to include. That is you need to specify all 4 version fields. You can, of course, do both methods, simple repository and name exact versions if you want the safety of that redundancy.

Communication

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 (add cross-project.inbox@eclipse.org to the "Add users to my watch list" box at the bottom of your Bugzilla email preferences page), 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.

Your representative to the Planning Council, either from PMC or Strategic Member, must attend Planning Council 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 issues that affect 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.

A build-team member or release engineer from each project must be "on call" during the aggregation or integration periods to make sure any issues can be addresses quickly.

Required Bundle forms and formats

Version Numbering (tested)

Projects must use 4-part version numbers following the common semantics described in the Eclipse version numbering document.

OSGi bundle format

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 bug 130598.)

Execution Environment (tested)

All plug-ins (that contain Java code) must correctly specify their Bundle Required Execution Environment (BREE). Resource-only bundles do not need a BREE since it doesn't matter which version of Java they are used with.

Signing (tested)

Projects must use signed plugins and features using the Eclipse certificate.

[added 12/2015, for Neon]. Note: If a jar is already signed by the Eclipse certificate, then it must not be re-signed by projects for the release train.

Jarred Bundles

Projects must use jarred plug-ins (with unpack=false) unless there are technical reasons not to (i.e. require the directory form).

License text consistency (tested)

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 Eclipse Foundation "about" template, 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, dates, and formatting. Note that the Eclipse Foundation's license or user agreement files may change from year to year (such as, see bug 316152 but since Indigo, it will be easier to point to a "symbolic" representation of the license, that is inserted at build time, so it will be accurate with less manual updates from each project (see bug 306818).

Re-use and share common third party code (partially tested)

Any third-party plug-ins that are common between projects must be consumed via Orbit. The Simultaneous Release must not have duplicate third-party libraries (note that this only applies to versions of the libraries; thus if project A requires foo.jar 1.6 and project B uses foo.jar 1.7, that's normally ok, different service versions a little less ok, such as 1.7.1 vs 1.7.2 (those should be explained, if required), and a qualifier-only difference is definitely not ok).

Note: the "partially tested", for this case, means there is a report of "Non Unique Versions used in repository" which can catch issues of not using common bundles. See current report for an example.

Provide optimized p2 repository (partially tested)

Projects must provide their own project p2 repository for their own project and updates. Projects must optimize their p2 repositories to reduce bandwidth utilization and provide a better install and update experience for users.

In addition, they must provide their artifacts 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 current process may be modified throughout the year, if improvements can be made.

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). This is mentioned since in some scenarios, only the pack.gz files needs to be left there ... but, that practice is controversial so for now we ask for both ... as one example, there are problems with Java 7 unpacking pack.gz files with nested jars (bug 361628).

Feature "includes" must be strict, that is "include" 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 since technically it is possible for people to use some p2 publishers that don't have this predictability or repeatability (which can certainly be appropriate in some contexts, just not the Simultaneous Release repository). While there may, in the future, be new mechanisms that allow some "line up collection" to be specified, it will be something new, not changing the meaning of feature "includes" element via p2 metadata.

For similar reasons, the repositories produced and contributed must use p2 publishers that produce greedy='false' in the content metadata for runtime-optional dependencies. See bug 247099 and the p2 Publisher wiki for some history and details on this issue of greedy vs. non-greedy requirements. But in brief, to have a runtime-optional dependency be non-greedy is important for several reasons, especially in an IDE environment. First it gives ultimate control over what is installed to the user, based on their feature selection, instead of depending on what happens to be available from the repositories they are pointing to at that moment it time. It also makes it much easier for adopters to be able to predict (and maintain) what their users have installed. In fact, if something is runtime-optional, but pulled into an install because someone did not specify greedy='false' meta-data, there is no way an adopter can provide a patch feature to one of their customers if that optional bundle causes a bug.

Everyone's p2 repositories must make use the of p2.mirrorsURL property. For "how to" information, see p2.mirrorsURL wiki. Note: this is not really a "Simultaneous Release Requirement" but is required of any p2 repository on Eclipse Foundation infrastructure, and is just documented here to help spread the word and educate newcomers.

Similar to p2.mirrorsURL attribute, a well behaved, well optimized p2 repository should contain a p2.index file. This is especially important for "composite repos" and prevents unnecessary "round trips" to server looking for files. See bug 347448 for history and for how-to instructions, see the p2 wiki. Again, this is not so much a "Simultaneous Release Requirement" but is recommended of any p2 repository on Eclipse Foundation infrastructure, and is just documented here to help spread the word and educate newcomers.

Branding

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 should contribute to the welcome page when appropriate.

Do No Harm

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 installed independently. If such a problem is identified, the affected projects must track down and fix the problem, to be in the simultaneous release repository.

Document Yearly Update Policy

It is required that participating projects document whether or not they support updating from one yearly release to the next. For example, from Neon (2016) to Oxygen (2017). [The current implementation plan for tracking, details TBD (see bug 509251), is for there to be a field in the PMI Release Record that must be checked "Yes" or "No".] To meet this requirement in the affirmative:

- The project will accept bugs as valid if an update does not work, or there is a functional problem after updating.
- The project will test such updates.
- The project will document, such as in a "Migration Guide" or "Release Notes", any details about what does or does not work across yearly updates. For example, a user's workspace may be "migrated" to the new release and not be usable by the old release after the update (but projects freshly checked out or imported would continue to work with either). Or, perhaps there are some known cases where some preference setting would be lost and have to be set again by the user.

Please note, this requirement is about documenting a project's policy. As of this writing (for Oxygen) it is possible for a project to simply document "No, updates from previous releases are not supported". In the future, after more experience is gained, it is anticipated that it will be required to support "continuous updates" even across yearly boundaries. The only reason we do not make it required at this point in time is that we are not sure we understand all the implications. Accordingly, bug 509237 has been opened to document "requirements or issues" that participating projects are aware of or find in support of this effort.

Also note, it is a given and documented elsewhere that "update releases" must be supported, such as updating from Neon to Neon.1, etc.

Optional Requirements

The items in this category are, in a sense, optional. That is, what, exactly, is done by a project is optional, but it is required for projects to document what they do. These are often "best practices" that many projects have found essential at driving good adoption, plus the items sometimes speak to the quality of the project (quality as an Eclipse "good citizen", as opposed to their code quality or architecture). But, their importance is not as universally relevant to all projects and their adopters, hence it is only required that each project document what they do for these items, but exactly what they do is up to the best judgment of the project and their community.

Please see the appendix for a detailed list of these items: Appendix: Required for good adoption

Additional Information



Retrieved from "https://wiki.eclipse.org/index.php?title=SimRel/Simultaneous_Release_Requirements&oldid=421209"

Back to the top