SimRel/Simultaneous Release Requirements PROPOSED

The Eclipse Simultaneous Release Requirements

WORK IN PROGRESS - This is not the official document but a staging area for proposed changes. Please see SimRel/Simultaneous_Release_Requirements for the actual official document.

Updated October 9, 2013

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)

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 Luna 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, ...)

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 XML Format (a normal Eclipse requirement). 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/kepler). 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 two planned Simultaneous 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. 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.

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 using the Eclipse certificate.

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.

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

• Planning Council Exception Process

• Testing of Simultaneous Release Repository