| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
| <title>The Eclipse Simultaneous Release</title> |
| </head> |
| <body> |
| <h1 style="text-align: center">The Eclipse Simultaneous Release</h1> |
| <h1 style="text-align: center; font-size: smaller">December 2, 2009<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>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><i>[New this year.]</i> Once in, always in. 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/helios) for end users |
| to discover easily and minimum requirements to be included in EPP Packages. The criteria in |
| this section are designed to make sure projects work relatively well, and work well |
| together. This is especially required for adopters who may be using |
| these projects in complicated, interwoven ways so each piece of the |
| puzzle must fit together well and be dependable and be maintainable, as |
| well as being on time and IP clean.</p> |
| <p><b>Communication</b>: |
| <p>At least one person from each project in a Simultaneous Release |
| must subscribe to cross-project mailing list, since that is the primary |
| communication channel for issues related to the Simultaneous Release. |
| Also, at least one person from each project must subscribe to |
| cross-project bugzilla inbox, as that is the primary bugzilla components |
| for bugs that are truly cross-project, or bugs which are not known to be |
| in one particular component.</p> |
| <p>Your representative to the Planning Council, either from PMC or |
| Strategic Member, must attend PC meetings and represent you there. |
| Presumably, of course, after meeting or communicating with you and the |
| other projects they represent, so they can fairly bring forward concerns |
| and vote on issue that effect all projects, if required. Put another |
| way, by committing to be in the Simultaneous Release, you agree to abide |
| by all the Planning Council decisions and rules, so be sure your |
| representative understands your project and your situation.</p> |
| <p>Build team members (or their designated |
| alternates) from each project may be asked to provide direct |
| communication channels: phone, mail, IM, IRC and at least one build team |
| member must be "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/Helios/Contributing_to_Helios_Build">current process</a> may be modified throughout the year, if improvements can be made. Clarification on 03/31/2010: At the <a |
| href="http://wiki.eclipse.org/Planning_Council/March_21_2010#Helios">3/21 |
| Planning Council meeting,</a> it was agreed this means that project's repositories must contain original jars, and pack.gz files (where original jar means the jar produced by the build, but which has been conditioned for pack200). </p> |
| <p><b>Capabilities</b>. Each project will provide basic |
| capability/activity definitions to allow for their UI contributions to |
| be hidden. These may be provided in a separate plugins and features to |
| facilitate inclusion and reuse by consumers in product development, or simply well |
| documented so adopters |
| can reuse via copy/paste. Ideally, projects should also provide |
| triggers to facilitate progressive discovery of functionality. |
| </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 Helios projects 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><i>[New this year.]</i> <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. You can see an example of the license-consolidating UI in |
| <a |
| href="http://download.eclipse.org/eclipse/downloads/drops/S-3.6M1-200908061400/eclipse-news-M1.html#Platform">Eclipse |
| Platform Helios M1</a>.</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>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/heliosPlan/index.php?title=Helios/Final_Daze&action=edit">Helios |
| 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 Helios 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><i>[New this year.]</i>. <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><i>[New this year.]</i>. <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><i>[New this year.]. </i><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><i>[New this year.]. </i><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></p> |
| <h1>Additional Information</h1> |
| <h2><a name="pcExceptionProcess">Planning Council Exception |
| Process</a></h2> |
| <p><i>[New this year.]</i> 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> |
