The Eclipse Simultaneous Release
December 1, 2010
Contact: David Williams
Note that as of Juno, around October, 2011, this document was moved to the Eclipse wiki. For latest content, please find at Eclipse Simultaneious Release Requirements.
This document defines the rules and criteria for participating in the yearly Simultaneous Release. There are more criteria than when releasing at other times partially because there are more projects releasing at once, so the workload needs to streamlined and made more uniform. More important, the extra criteria are included by mutual agreement between projects (via their representatives to Planning Council) so that as a whole, the release will be of better quality, maintainability, and improved consumability by adopters.
The spirit of this document should not be so much as a "contract" of what has to be done to release, but instead as an agreement to make the Yearly Release good, if not great! While each Project does their individual things to make the Release great, this document and process describe how we as a group document the achievement of our agreement. We are always open to better agreements and better documentation of our achievements so feel free to keep track and make suggestions year-to-year (preferably through your Planning Council representative) on how to make our yearly release better. In fact, occasionally changes may be made to this document for clarity or to improve reference links throughout the development cycle, but nothing new that would change work-load will be added after M4.
To foster communication and flexibility where required, any exceptions to these criteria or deadlines will follow the Planning Council Exception Process.
The requirements are divided into three categories:
- Requirements to be released as part of the "yearly release", normal release requirements, done earlier than usual.
- Requirements to be part of the Common Discovery Site repository and, consequently, the minimum requirements to be part of EPP packages.
- Requirements to demonstrate good Eclipse Citizenship, following "the Eclipse Way".
Do the basics ... early
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.
To join a Simultaneous Release, Projects must have stated their intent to do so, and be in a build for the composite site aggregation by M4, at the latest. For projects continuing from previous years, the expectation is they will be in M1, unless they formally withdraw.
The "statement of intent" is done formally by marking the "Simultaneous Release Flag" in the project's Portal meta-data.
All projects must have their project plan in the Eclipse Foundation standard XML Format (a normal Eclipse requirement). Committing to be in the Simultaneous Release means you commit to having these plans early: M2, for those projects that already know they will be in the Simultaneous Release, M4 will be the latest possible time, for those projects that are new to the Simultaneous Release Train and decide to join after M2. The plans should be updated periodically as things change, or as items are completed.
Also, for long term planning, remember that being in a Simultaneous Release also means a commitment to participating the SR1 and SR2 simultaneous maintenance releases.
Joining implies continuous participation. After a release, there are two follow on activities that must be planned for. First is that releases maintenance stream. The second is the subquent year's release. In both cases, it is (as always) up to the project to decide what to fix or what to enhance, but being part of the train implies you will always be able to build, in maintenance and in the subsequent release's milestone builds. Sometimes this means simply leaving repositories intact, etc., but occasionally projects may need to fix "prereqs" or similar. Put another way, being part of the Simultaneous Release is not a "one time" activity, covering only the literal release date and not even a "part time" activity covering only part of the yearly development cycle. Instead it is a commitment to stay "simultaneous" on an on-going basis. Once in, if projects decide to not be part of future simultaneious releases, they need to communicate that widely, and as early as possible, since could effect adopters or downstream projects.
Projects must have their IP Logs approved (a normal Eclipse requirement) and will follow the Eclipse Legal deadlines to do so. In addition, drafts of the Projects IP Logs must be available early, starting with M5. The development process requires the IP Log to always be accurate, but experience shows there's always some issues that have to be resolved, or fixed, before release (for example, sometimes a CQ might have the wrong flag, and cause it to not show up in the Auto IP Log). It is expected the IP Logs should be relatively complete by M7. If Projects have changes come in after M7 they can update until the deadline set by the IP staff (usually RC2). The purpose of having these early drafts is so that projects get familiar with what's required, and do not allow work to build up at the end, also to allow questions to come up, and have time to find answers, and also to allow time for issues with automatic IP tools to be addressed. Some adopters will want to look at these early drafts to see what 3rd party requirements are associated with the code.
Being in the Simultaneous Release will give your IP some higher priority in getting evaluated, in order to make the date. The higher priority treatment is only for the 5 months or so before the release (after the deadline for CQs). The reason being, of course, is that the rest of the year the IP staff must also get work done for maintenance releases and projects not on the release train. During that part of the year (roughly July to February every year) all CQs are prioritized in a uniform way.
The release review archival materials must be complete by the date specified by the EMO, which is usually staged in earlier than for a usual release. (Typically RC2.)
A Project's PMC must approve the projects request for review (a normal Eclipse requirement). In addition, to help organize and streamline the yearly Simultaneous release, a PMC must provide their approval in writing, in the form of a short summary of their projects that are requesting review and summary of the PMC's discussion or method of approving them. (This is meant to be very brief, such as 1/2 to 1 page). The short summary can be documented in a mailing list, PMC Meeting notes, or even a wiki document. A pointer (URL) to the document should be provided to EMO, and will be included in the same notice to the community that provides pointers to the Project Docuware.
The public review calls will be organized based on Top Level Project, and at least one PMC member should be on that call to give very brief overview of projects that are requesting the release review (not to exceed 5 minutes, at the very most).
In addition to the ordinarily required Release Review Archival Materials, all Projects participating in yearly Release agree to provide a checklist-with-detail form that describes their compliance (or not) with all of the criteria items described in this document. May be in the form of providing a URL to the checklist, ideally as part of the normal docuware. Note that this checklist-with-detail must be updated every milestone as things are completed, or details added, so progress can be reviewed by Planning Council and potential adopters. The primary report of compliance with the checklist must be provided at least at the level of a Top Level Project. In some cases, such as if sub-projects are very independent of each other, PMCs may decide to document things at a subproject level, and then "roll-up" to a Top Level document, or, if a Top Level Project is known to be uniform and "close knit" then they may provide one summary document that applies to all sub-projects.
Play well with others ... to be in common repository
The requirements in this section must be met for a project to be on the common, central repository (e.g. /releases/helios) for end users to discover easily and minimum requirements to be included in EPP Packages. The criteria in this section are designed to make sure projects work relatively well, and work well together. This is especially required for adopters who may be using these projects in complicated, interwoven ways so each piece of the puzzle must fit together well and be dependable and be maintainable, as well as being on time and IP clean.
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.
Your representative to the Planning Council, either from PMC or Strategic Member, must attend PC meetings and represent you there. Presumably, of course, after meeting or communicating with you and the other projects they represent, so they can fairly bring forward concerns and vote on issue that effect all projects, if required. Put another way, by committing to be in the Simultaneous Release, you agree to abide by all the Planning Council decisions and rules, so be sure your representative understands your project and your situation.
Build team members (or their designated alternates) from each project may be asked to provide direct communication channels: phone, mail, IM, IRC and at least one build team member must be "on call" during the milestone integration periods.
API. 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.
Message Bundles. Projects must use Eclipse message bundles unless there are technical reasons not to.
Version Numbering. Projects must use 4-part version numbers.
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. All plug-ins must correctly list their Bundle Required Execution Environment (BREE).
Signing. 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 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.
Re-use and share common third party jars. Any third-party plug-ins that are common between projects must be consumed via Orbit; a Simultaneous Release will not have duplicate third-party libraries (note that this only applies to identical versions of the libraries; thus if project A requires foo.jar 1.6 and project B uses foo.jar 1.7, that's ok, as long as it is required and has a documented reason).
Optimization. Projects must optimize their p2 repositories to reduce bandwidth utilization and provide a better install and update experience for users.
Provide p2 repository. 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 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.
Support Translations. 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).
Excel in NL support. The Project must use ICU4J, where appropriate, to excel in NL support. (The latest ICU4J bundles will be in Orbit).
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.
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.
License text consistency. 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, arbitrary 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).
Support Primary Eclipse Platform to be in EPP Package. For Indigo, that means EPP packages (and the features and bundles that go into them) must be built on and tested with Eclipse 3.7.
Be a good Eclipse Citizen ... and document it
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.
Engage Community. 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 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.
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. [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 program. For example, while using an English version of Eclipse Web Tools, someone should be able to create a Chinese language web application. [Need "how to" reference link.]
Builds. Projects must have a mature, stable build process: documented, scripted, repeatable, and executable by others.
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 Platform 3.5 Endgame plan as a guideline. See also 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
but, given the 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 NVDA. The main accessibility article at Eclipse Corner has been made current (thanks goes to Todd Creasey).
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.
Retention Policy. Projects should define and document their retention policy. This should include both zip distributions and repositories. For examples, see WTP Retention Policy and 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.
Specify in Plans, support for auxiliary, or future Eclipse Platforms. For Indigo, this means that each project needs to have a section (or theme) in their plans (and, that's the standard format plan), on how they intend to support Eclipse 4.1. The ideal statement would be to the effect that the project will run and has been tested on 4.1. And, projects that exploit anything specific to 4.1 should explain that too. Naturally, since each project has their own plans and priorities, and one possibility is to plan "no support, no testing on 4.1". The purpose of this requirement is to be clear on your plans and communicate those to the community.
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:
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 automatation may be added to the release reporting tool to aid this documentation.