| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
| <title>The Eclipse Simultaneous Release</title> |
| </head> |
| <body> |
| <h1 style="text-align: center">The Eclipse Simultaneous Release</h1> |
| <h1 style="text-align: center; font-size: smaller">November 8, 2010<br /> |
| <a href="http://wiki.eclipse.org/Planning_Council">Eclipse Planning |
| Council</a><br /> |
| Contact: <a href="mailto: david.williams@eclipse.org">David Williams</a></h1> |
| |
| <p><i>Note: This document, for Indigo release, has yet to be |
| formally reviewed and approved by the Eclipse Planning Council. It is |
| unlikely to change substantially, but could have items added or removed |
| up to M4. After M4, only clarifications or changes in wording would |
| occur, no changes to expectations or requirements.</i></p> |
| |
| <p>This document defines the rules and criteria for participating in |
| the yearly Simultaneous Release. There are more criteria than when |
| releasing at other times partially because there are more projects |
| releasing at once, so the workload needs to streamlined and made more |
| uniform. More important, the extra criteria are included by mutual |
| agreement between projects (via their representatives to Planning |
| Council) so that as a whole, the release will be of better quality, |
| maintainability, and improved consumability by adopters.</p> |
| <p>The spirit of this document should not be so much as a "contract" |
| of what has to be done to release, but instead as an agreement to make |
| the Yearly Release good, if not great! While each Project does their |
| individual things to make the Release great, this document and process |
| describe how we as a group document the achievement of our agreement. We |
| are always open to better agreements and better documentation of our |
| achievements so feel free to keep track and make suggestions |
| year-to-year (preferably through your Planning Council representative) |
| on how to make our yearly release better. In fact, occasionally changes |
| may be made to this document for clarity or to improve reference links |
| throughout the development cycle, but nothing new that would change |
| work-load will be added after M4.</p> |
| <p>To foster communication and flexibility where required, any |
| exceptions to these criteria or deadlines will follow the <a |
| href="#pcExceptionProcess">Planning Council Exception Process</a>.</p> |
| <p>The requirements are divided into three categories:</p> |
| <ol> |
| <li>Requirements to be released as part of the "yearly |
| release", normal release requirements, done earlier than usual.</li> |
| <li>Requirements to be part of the Common Discovery Site |
| repository and, consequently, the minimum requirements to be part of |
| EPP packages.</li> |
| <li>Requirements to demonstrate good Eclipse Citizenship, |
| following "the Eclipse Way".</li> |
| </ol> |
| |
| <h2>Do the basics ... early</h2> |
| <p>The requirements and conditions stated in this section are the |
| basic minimum required for a project to claim they are part of the |
| yearly Simultaneous Release.</p> |
| <p>To join a Simultaneous Release, Projects must have stated their |
| intent to do so, and be in a build for the composite site aggregation by |
| M4, at the latest. For projects continuing from previous years, the |
| expectation is they will be in M1, unless they formally withdraw.</p> |
| <p>The "statement of intent" is done formally by marking |
| the "Simultaneous Release Flag" in the project's Portal |
| meta-data.</p> |
| <h3>Planning</h3> |
| <p>All projects must have their project plan in the Eclipse |
| Foundation standard XML Format (a normal Eclipse requirement). |
| Committing to be in the Simultaneous Release means you commit to having |
| these plans early: M2, for those projects that already know they will be |
| in the Simultaneous Release, M4 will be the latest possible time, for |
| those projects that are new to the Simultaneous Release Train and decide |
| to join after M2. The plans should be updated periodically as things |
| change, or as items are completed.</p> |
| <p>Also, for long term planning, remember that being in a |
| Simultaneous Release also means a commitment to participating the SR1 |
| and SR2 simultaneous maintenance releases.</p> |
| <p><b>Once in, always in.</b> Once a project joins one year's |
| Simultaneous Release, it is assumed they will be in the next one, unless |
| they formally withdraw. So, for example, it is required they will meet |
| the subsequent year's Milestone Schedule, have plans done by M2 of |
| following year, etc. Put another way, being part of the Simultaneous |
| Release is not a "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.</p> |
| |
| |
| <h3>IP Documentation</h3> |
| <p>Projects must have their IP Logs approved (a normal Eclipse |
| requirement) and will follow the Eclipse Legal deadlines to do so. In |
| addition, drafts of the Projects IP Logs must be available early, |
| starting with M5. The development process requires the IP Log to always |
| be accurate, but experience shows there's always some issues that have |
| to be resolved, or fixed, before release (for example, sometimes a CQ |
| might have the wrong flag, and cause it to not show up in the Auto IP |
| Log). It is expected the IP Logs should be relatively complete by M7. If |
| Projects have changes come in after M7 they can update until the |
| deadline set by the IP staff (usually RC2). The purpose of having these |
| early drafts is so that projects get familiar with what's required, and |
| do not allow work to build up at the end, also to allow questions to |
| come up, and have time to find answers, and also to allow time for |
| issues with automatic IP tools to be addressed. Some adopters will want |
| to look at these early drafts to see what 3rd party requirements are |
| associated with the code.</p> |
| <p>Being in the Simultaneous Release will give your IP some higher |
| priority in getting evaluated, in order to make the date. The higher |
| priority treatment is only for the 5 months or so before the release |
| (after the deadline for CQs). The reason being, of course, is that the |
| rest of the year the IP staff must also get work done for maintenance |
| releases and projects not on the release train. During that part of the |
| year (roughly July to February every year) all CQs are prioritized in a |
| uniform way.</p> |
| <h3 id="pcReleaseReview">Release Review</h3> |
| <p>The release review archival materials must be complete by the |
| date specified by the EMO, which is usually staged in earlier than for a |
| usual release. (Typically RC2.)</p> |
| <p>A Project's PMC must approve the projects request for review (a |
| normal Eclipse requirement). In addition, to help organize and |
| streamline the yearly Simultaneous release, a PMC must provide their |
| approval in writing, in the form of a short summary of their projects |
| that are requesting review and summary of the PMC's discussion or method |
| of approving them. (This is meant to be very brief, such as 1/2 to 1 |
| page). The short summary can be documented in a mailing list, PMC |
| Meeting notes, or even a wiki document. A pointer (URL) to the document |
| should be provided to EMO, and will be included in the same notice to |
| the community that provides pointers to the Project Docuware.</p> |
| <p>The public review calls will be organized based on Top Level |
| Project, and at least one PMC member should be on that call to give very |
| brief overview of projects that are requesting the release review (not |
| to exceed 5 minutes, at the very most).</p> |
| <p>In addition to the ordinarily required Release Review Archival |
| Materials, all Projects participating in yearly Release agree to provide |
| a checklist-with-detail form that describes their compliance (or not) |
| with all of the criteria items described in this document. Note that |
| this checklist-with-detail must be updated every milestone as things are |
| completed, or details added, so progress can be reviewed by Planning |
| Council and potential adopters. The primary report of compliance with |
| the checklist must be provided at least at the level of a Top Level |
| Project. In some cases, such as if sub-projects are very independent of |
| each other, PMCs may decide to document things at a subproject level, |
| and then "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. [This |
| will likely be automated as web-app, possibly with "automatic" |
| roll up].</p> |
| <p></p> |
| <h2>Play well with others ... to be in common repository</h2> |
| <p>The requirements in this section must be met for a project to be |
| on the common, central repository (e.g. /releases/indigo) for end users |
| to discover easily and minimum requirements to be included in EPP |
| Packages. The criteria in this section are designed to make sure |
| projects work relatively well, and work well together. This is |
| especially required for adopters who may be using these projects in |
| complicated, interwoven ways so each piece of the puzzle must fit |
| together well and be dependable and be maintainable, as well as being on |
| time and IP clean.</p> |
| <p><b>Communication</b>:</p> |
| <p>At least one person from each project in a Simultaneous Release |
| must subscribe to cross-project mailing list, since that is the primary |
| communication channel for issues related to the Simultaneous Release. |
| Also, at least one person from each project must subscribe to |
| cross-project bugzilla inbox, as that is the primary bugzilla components |
| for bugs that are truly cross-project, or bugs which are not known to be |
| in one particular component.</p> |
| <p>Your representative to the Planning Council, either from PMC or |
| Strategic Member, must attend PC meetings and represent you there. |
| Presumably, of course, after meeting or communicating with you and the |
| other projects they represent, so they can fairly bring forward concerns |
| and vote on issue that effect all projects, if required. Put another |
| way, by committing to be in the Simultaneous Release, you agree to abide |
| by all the Planning Council decisions and rules, so be sure your |
| representative understands your project and your situation.</p> |
| <p>Build team members (or their designated alternates) from each |
| project may be asked to provide direct communication channels: phone, |
| mail, IM, IRC and at least one build team member must be "on |
| call" during the milestone integration periods.</p> |
| <p><b>API</b>. Projects should leverage only published APIs of |
| dependencies. All deviations must be documented in bugzillas. These |
| bugzillas may be of the type that a dependent project should provide a |
| required API, or of the type that a consuming project must move to some |
| API that already exists. Note that technically there is no obligation |
| for consumed projects to provide API that is requested ... that depends |
| on many things ... but the main goal of requiring these bugzilla entries |
| is to provide some documentation and measure of the amount of risk |
| associated with non-API use.</p> |
| <p><b>Message Bundles</b>. Projects must use <a |
| href="http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/reference/misc/message_bundles.html"> |
| Eclipse message bundles</a> unless there are technical reasons not to.</p> |
| <p><b>Version Numbering</b>. Projects must use 4-part <a |
| href="http://wiki.eclipse.org/Version_Numbering">version numbers</a>.</p> |
| <p><b>OSGi bundle format</b>. All plug-ins (bundles) must use the |
| true bundle form. That is, provide a manifest.mf file, and not rely on |
| the plugin.xml file being 'translated' into a manifest.mf file at |
| initial startup. With that, empty plugin.xml files in the presence of a |
| manifest.mf file should not be included in a bundle. (For some old |
| history, see <a |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=130598">bug |
| 130598</a>.)</p> |
| |
| <p><b>Execution Environment</b>. All plug-ins must <a |
| href="http://wiki.eclipse.org/Execution_Environments">correctly |
| list their Bundle Required Execution Environment (BREE)</a>.</p> |
| |
| <p><b>Signing</b>. Projects must use <a |
| href="http://wiki.eclipse.org/JAR_Signing">signed plugins using the |
| Eclipse certificate</a>.</p> |
| |
| <p><b>Jarred Bundles</b>. Projects must use jarred plug-ins (with |
| unpack=false) unless authorized by the planning council for technical |
| exceptions. Also, nested jars should be avoided if possible since it |
| creates problems for projects that has dependencies to such plug-ins. |
| The OSGi runtime is fine with it but the PDE environment is not able to |
| handle classpaths that contain nested jars.</p> |
| <p><b>Re-use and share</b><b> </b>common third party jars. Any |
| third-party plug-ins that are common between projects must be consumed |
| via <a href="http://www.eclipse.org/orbit">Orbit</a>; a Simultaneous |
| Release will not have duplicate third-party libraries (note that this |
| only applies to identical versions of the libraries; thus if project A |
| requires foo.jar 1.6 and project B uses foo.jar 1.7, that's ok, as long |
| as it is required and has a documented reason).</p> |
| |
| <p><b>Optimization</b>. Projects must <a |
| href="http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/guide/p2_repositorytasks.htm"> |
| optimize their p2 repositories</a> to reduce bandwidth utilization and |
| provide a better install and update experience for users.</p> |
| <p><b>Provide p2 repository</b>. Projects must provide their own |
| project p2 repository for their own project and updates. In addition, |
| they must provide their archives and metadata in a specified format and |
| method to allow at least parts of their repository to be aggregated and |
| mirrored to a common repository. The <a |
| href="http://wiki.eclipse.org/Indigo/Contributing_to_Indigo_Build">current |
| process</a> may be modified throughout the year, if improvements can be |
| made. Clarification on 03/31/2010: Note that a project's |
| repositories must contain original (conditioned) jars, and pack.gz files (where |
| original jar means the jar produced by the build, but which has been |
| conditioned for pack200). Clarification on 11/08/2010: feature |
| "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.</p> |
| <p><b>Support Translations</b>. All strings must be externalized, |
| and Projects must participate in Babel, meaning it is registered and |
| available for string translation, etc. Projects must freeze the UI |
| sufficiently early to allow the Babel project time to translate strings |
| so there can be simultaneous release of translated versions. The UI |
| should be frozen by M6 (a "freeze" all major changes and additions are |
| done by M6, and changes after that are done in a controlled, well |
| documented fashion, so Babel translators can more easily "keep |
| up" with late changes).</p> |
| <p><b>Excel in NL support</b>. The Project must use <a |
| href="http://wiki.eclipse.org/ICU4J">ICU4J</a>, where appropriate, to |
| excel in NL support. (The latest ICU4J bundles will be in Orbit).</p> |
| <p><b>Branding</b>. Each major project (as determined by |
| participating PMCs) must have an 'About' dialog icon with hover text |
| that displays the provider name. Every plug-in and feature must specify |
| a descriptive provider-name (for features), or Bundle-Vendor header (for |
| plug-ins), as determined by the project's PMC (e.g. "Eclipse Modeling |
| Project" rather than "Eclipse.org"). Also, Projects must contribute to |
| the welcome page when appropriate.</p> |
| |
| |
| |
| |
| |
| <p><b>Do No Harm.</b> Projects must work together in any combination |
| of any install. Put another way, this means that users can install any |
| subset of the projects participating in Simultaneous Release, and each |
| of the installed projects will work as well as if it had been loaded |
| independently. If such a problem is identified, the affected projects |
| must track down and fix the problem.</p> |
| <p><b>License text consistency</b>. Use standard forms of license |
| documents so it is displayed in the most usable, and concise way during |
| install and update. It is a normal requirement to use a standard <a |
| href="http://www.eclipse.org/legal/epl/about.php">Eclipse |
| Foundation "about" template</a>, but where those templates are |
| edited by each project, care must be taken to be sure they are edited in |
| similar ways. That is, substantial differences are fine, if required, but we need to avoid minor differences based on case, |
| arbitrary dates, and formatting. Note that the Eclipse Foundation's license or user |
| agreement files may change from year to year (such as, see <a |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=316152">bug |
| 316152</a>) but ideally in Indigo and future releases, it will be easier to |
| point to a "symbolic" representation of the license, so it |
| will be accurate with less manual updates from each project (see <a |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=306818">bug |
| 306818</a>).</p> |
| |
| <p><b>Support Primary Eclipse Platform to be in EPP Package.</b> For |
| Indigo, that means EPP packages (and the features and bundles that go |
| into them) must be built on and tested with Eclipse 3.7.</p> |
| <h2>Be a good Eclipse Citizen ... and document it</h2> |
| <p>Projects should exhibit good Eclipse Citizenship, to Release and |
| participate in Common Discovery Site and EPP Packages. These are often |
| "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.</p> |
| <p><b>Engage Community</b>. The Project should actively engage their |
| community to get feedback on milestone builds, and document how they do |
| that. One way to do this is to have a <a |
| href="http://wiki.eclipse.org/Architecture_Council/New_and_Noteworthy">New |
| & Noteworthy</a> for each milestone. New and Noteworthy documents should |
| be something readable and usable not just a static list of all the bugs. |
| Corollary: individual new & noteworthy should be linked in to the |
| collective New & Noteworthy.</p> |
| <p><b>Usability</b>. Should follow the <a |
| href="http://wiki.eclipse.org/User_Interface_Guidelines">User |
| Interface Guidelines</a>. The <a href="http://wiki.eclipse.org/UI_Checklist">UI |
| Checklist</a> is a good place to start. Also, should participate in a <a |
| href="http://wiki.eclipse.org/User_Interface_Best_Practices_Working_Group">User |
| Interface Best Practices Working Group</a> <a |
| href="http://wiki.eclipse.org/UIBPWG_UI_Walkthrough"> UI |
| walkthrough</a>.</p> |
| <p><b>Performance</b>. Project should have measurable performance |
| criteria that are regularly tested against. Projects should devote at |
| least one milestone to performance and scalability improvements.</p> |
| <p><b>Test Localization</b>. The project should use the <a |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=217339">Babel |
| Pseudo Translation Test</a> to verify their translatability. [Need better |
| reference link.]</p> |
| <p><b>Capabilities</b>. Each project should provide basic |
| capability/activity definitions to allow for their UI contributions to |
| be hidden. These can be provided in a separate plugins and feature to |
| facilitate inclusion and reuse by consumers, or ... as most projects do |
| ... simply document some examples, so adopters can create their own, or |
| reuse via copy/paste. Ideally, projects should also provide triggers to |
| facilitate progressive discovery of functionality (but, not many do, |
| other than the Platform). As with other "good citizen" items, |
| projects are free to document "we don't do this" ... but, then |
| at least it is known and better communicated.</p> |
| <p><b>Enable Use with All Languages</b>. Should design and test for |
| enabling all languages including bidi, unicode characters, etc. This is |
| different than "translating" the program. For example, while using an |
| English version of Eclipse Web Tools, someone should be able to create a |
| Chinese language web application. [Need "how to" reference link.]</p> |
| <p><b>Builds</b>. Projects must have a mature, stable build process: |
| documented, scripted, repeatable, and executable by others.</p> |
| <p><b>Ramp Down Planned and Defined</b>. Projects must have a |
| written ramp down policy by M6, at the latest, and provide link. The |
| plan should describe when the project plans to be feature complete, have |
| API frozen, and similar. See <a |
| href="http://www.eclipse.org/eclipse/development/freeze_plan_3.5.php">Platform |
| 3.5 Endgame plan</a> as a guideline. See also <a |
| href="http://wiki.eclipse.org/indigoPlan/index.php?title=Indigo/Final_Daze&action=edit">Indigo |
| Final Daze</a>.)</p> |
| <p><b>Accessibility</b>. Projects should design and test for |
| accessibility compliance, following established guidelines and Eclipse |
| fundamental techniques to achieve accessibility. Projects must document |
| their accessibility work and compliance. Ideally this would be by using |
| a publicly available checklists, such as</p> |
| <ul> |
| <li><a |
| href="http://www.itic.org/resources/voluntary-product-accessibility-template-vpat/">http://www.itic.org/resources/voluntary-product-accessibility-template-vpat/ |
| </a></li> |
| <li><a href="http://www.section508.gov/">http://www.section508.gov/</a></li> |
| <li><a href="http://www.w3.org/TR/WCAG/">http://www.w3.org/TR/WCAG/</a></li> |
| </ul> |
| <p>but, given the <a |
| href="http://wiki.eclipse.org/Planning_Council/Cross_Project_Teams/Accessibility">advice |
| of the Accessibility Cross Project Team</a>, for this year's |
| Simultaneous Release, projects can document their work or compliance as |
| a negative, such as "we did not do any accessibility work or testing and |
| do not know the degree of our compliance". But its important to |
| document, so adopters know. If possible, and appropriate, accessibility |
| testing tools can be leveraged such as <a |
| href="http://www.nvda-project.org/">NVDA</a>. The main <a |
| href="http://www.eclipse.org/articles/article.php?file=Article-Accessibility351/index.html">accessibility |
| article at Eclipse Corner</a> has been made current (thanks goes to Todd |
| Creasey).</p> |
| |
| <p><b>Unit Tests</b>. Projects must have some unit tests that can |
| verify at least basic functionality of a build or distribution. The |
| steps to build and run the tests must be documented and executable by |
| others.</p> |
| <p><b>API Policy</b> Defined and Documented. Typically would include |
| how 'APIs' are distinguished from non-API and 'provisional' API, if any. |
| It is recommended that non-API be marked with x-internal in the bundles |
| manifest. Also, should include what the commitment is to API, how long |
| maintained after deprecated, etc. As one example, see <a |
| href="http://wiki.eclipse.org/WTP_API_Policy">WTP API Policy</a>.</p> |
| |
| <p><b>Retention Policy.</b> Projects should define and document |
| their retention policy. This should include both zip distributions and |
| repositories. For examples, see <a |
| href="http://wiki.eclipse.org/WTP/Retention_Policy">WTP Retention |
| Policy</a> and <a |
| href="http://wiki.eclipse.org/Eclipse_Project_Update_Sites">Eclipse |
| Project Update Sites</a></p> |
| <p><b>Project Metrics.</b> Projects should provide some summary |
| metrics, such as number of bundles, number of committers, lines of code, |
| number of bugs opened and fixed. This is so some statements can be made |
| and tracked year-to-year about the size of the simultaneous release.</p> |
| |
| <p><b>Specify in Plans, support for auxiliary, or future Eclipse |
| Platforms.</b> For Indigo, this means that each project needs to have a |
| section (or theme) in their plans (and, that's the standard format |
| plan), on how they intend to support Eclipse 4.1. The ideal statement |
| would be to the effect that the project will run and has been tested on |
| 4.1. And, projects that exploit anything specific to 4.1 should explain |
| that too. Naturally, since each project has their own plans and |
| priorities, and one possibility is to plan "no support, no testing on |
| 4.1". The purpose of this requirement is to be clear on your plans and |
| communicate those to the community.</p> |
| |
| <p></p> |
| <h1>Additional Information</h1> |
| <h2><a name="pcExceptionProcess">Planning Council Exception |
| Process</a></h2> |
| <p>Exceptions for any rule or schedule can be made if there are good |
| enough reasons to. This same exception process will be followed for |
| things like "requests to respin" a build after a deadline. The |
| process to get any exception must be open and well documented and follow |
| these steps:</p> |
| <p>First, the Project's PMC must approve the request for an |
| exception and it is the PMC (not the Project) that makes the request to |
| the Planning Council. The Planning Council member that represents the |
| PMC would bring the issue forward to the Planning Council.</p> |
| <p>Second, the exception requires at least 3 positive votes from |
| active Planning Council members and no negative votes. When time is a |
| factor (e.g. requests for rebuilds) the deadline for voicing a negative |
| vote is basically by the time 3 votes are documented. But when time is |
| not a factor, such as when requesting an exception to one of the |
| criteria, then a period of one week will pass before being final, to |
| allow times for concerns or negative votes to be voiced even after 3 |
| positive votes. If there are not enough positive votes within one week, |
| then the request for exception will be considered 'failed'. Note that |
| "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.</p> |
| <p>Depending on the timing, the issue and votes will be documented |
| in either the Planning Council Meeting minutes, or on the Planning |
| Council mailing list. If possible, some automatation may be added to the |
| release reporting tool to aid this documentation.</p> |
| </body> |
| </html> |
