Difference between revisions of "SimRel/Simultaneous Release Requirements/Appendix"
|Line 133:||Line 133:|
Projects should design and test for enabling development for all languages including bidi, unicode characters, etc. This is different than "translating" the User Interface and would apply even to "runtime only" components. For one example, while using an English version of Eclipse Web Tools Platform, someone should be able to create a Chinese language web application and have it (and debug logs) displayed correctly.
Revision as of 10:35, 2 October 2013
- 1 Simultaneous Release Requirements Appendix
- 1.1 Normal Release Requirements
- 1.2 Required for good adoption
- 1.2.1 Engage Community
- 1.2.2 Usability
- 1.2.3 Performance
- 1.2.4 Builds
- 1.2.5 Unit Tests
- 1.2.6 Ramp Down Planned and Defined
- 1.2.7 Accessibility
- 1.2.8 APIs
- 1.2.9 Retention Policy
- 1.2.10 Make it easy to get released source from repository
- 1.2.11 Excel in National Language support
- 2 Additional Information
Simultaneous Release Requirements Appendix
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 2, 2013
Authored and maintained by the Eclipse Planning Council
Contact: David Williams
This document is an appendix to the Simultaneous Release Requirements document, and is intended to provide supplementary information for the primary document. This may be in the form of greater detail or explanations for a stated requirement. It is generally intended to be used as a reference from the primary document, and not read on its own.
Normal Release Requirements
Formal (standard format) plans, early (M4)
It would be anticipated that this year, for Kepler, many Eclipse users would still be using Java 6, but projects should test extensively on Java 7. In general, it is recommended to write your code to the lowest level possible, but test on the highest level possible.
To satisfy this requirement, please document your supported platforms in your standard project plan by having a section labeled, exactly, as <target_environments>. See template in standard plan reference and for an example, other than the Platform's, see the subject section in Web Tools plan.
Be sure to raise any "target platform level" questions or issues to the cross-project list, especially if a your project is "moving up" a level and might affect projects or adopters that depend on it.
Compatibility with Previous Releases
Note: this primarily applies to projects that have "released before", but even those releasing for the first time should be aware of this requirement as there could be things done "now" for future compatibility and migration ... these need to be "thought through" even for your first release, to make sure your second release maintains appropriate compatibility.
IP Documentation and Logs (RC1)
Projects are encouraged to create drafts of the Projects IP Logs even earlier. The development process requires the IP Log to always be accurate, but experience shows there often are not, until examined for a release, and there are typically many issues to resolve, or fixed, before the final submission to the IP staff. For example, sometimes a CQ might have the wrong flag, and cause it to not show up in the Auto IP Log, or perhaps a common, already approved 3rd party jar was was used, but no CQ for that specific project entered one for the new version. The purpose of having these early drafts is so that projects get familiar with what is required, and do not allow work to build up until the ver, since that could cause a "bottleneck" at a critical time and jeopardize having the ability to resolve all issues in time to be released. Also, some adopters will want to look at early drafts to see what 3rd party requirements are associated with the code they are planning to adopt.
A good guideline is to have a draft of your IP Log by M5, and plan for it to be complete for M7.
Release Review and compliance to requirements documentation (RC3)
Normally, in release review documentation, Project Leads must document and state that the project's release complies with all the normal release requirements, such as IP requirements. In addition, 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. [This is the replacement or "low cost alternative" to tracking on Foundation Portal, which was deemed unmaintainable. Eventually some of the URLs etc. requested in the old tracking system will be in the new "release portal" but not yet (see bug 363524.]
Required for good adoption
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 be 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.
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 a collective New & Noteworthy.
Project should have measurable performance criteria that are regularly tested against. Projects should devote at least one milestone to performance and scalability improvements. This is important to the Simultaneous Release since a project or plugin by itself might seem to perform ok, but taken together as part of hundreds of bundles, it might cause in unusable performance.
Projects must have a mature, stable build process: documented, scripted, repeatable, and executable by others on their own system. Ideally there would be just a few commands to run from a Linux shell to accomplish the build, but there might need to be a page of "set up" instructions of what's required (e.g. if Git needs to be installed, certain version of Java, etc.) Of course, there may be some parts of it that do not work completely (such as, being signed by the Eclipse code certificate would not work when ran by others, on non-Eclipse.build systems) but the build should not fail if it does not sign, and otherwise should produce essentially the same functional output as the "officially signed build". Note, this build should include both producing the code and producing the runnable unit tests.
Projects should have unit tests with enough documented instructions that others (adopters or extenders) can run in their own environments and configurations, independent of doing a build. Ideally this could be done with just a few commands, but as with builds, might require a description of machine set-up.For one, example, see WTP Stand alone unit tests.
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 Juno Final Daze.)
See the WTP Accessibility Page for how one project documented their checklists.
Note, projects can document their work or compliance as a negative, such as "We do not do any accessibility work or testing and do not know the degree of our compliance. While we will consider accessibility bugs as valid, it is unlikely we would give them a high priority". But its important to document if that is the case, so adopters know.
If possible, and appropriate, accessibility testing tools can be leveraged such as NVDA.
The main accessibility article at Eclipse Corner is also very helpful. (thanks goes to Todd Creasey).
Use only APIs
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.
Document APIs provided and publish API policy
APIs should be provided, so others can properly extend functionality, and presumably most of that detail is defined in JavaDoc. But, there should be a high level statement of how consuming projects can determine what is API; 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 bundle's manifest. Also, API policy should include what the commitment is to API, how long maintained after deprecated, etc. As one example, see WTP API Policy.
Make it easy to get released source from repository
Projects should make it easy for potential contributers (and adopters) to get the source used in the release, from the source control repository (that is, source that exactly matches what was used in a build or release). This might be done by some form of documentation, or tag, or by producing a "team project set" during your build and making that available from your downloads page.
Another good way to accomplish this, while maybe not suitable for all projects, is to make your bundle's source repository "self documenting" by using the Eclipse-SourceReference directive in your manifest.mf file (its very easy to have this added if your build makes use of PDE build or its properties). This requirement serves two purposes.
First, we want to be sure adopters can get your source used in a release, in case they need to create some fix, even at some distant point in the future. But, also, this serves the community purpose of making it easier for contributors to provide patches for bugs.
Excel in National Language support
Use the best NL Java Libraries (ICU4J)
Projects should use ICU4J, where they have "user strings", in order to excel in NL support. (The latest recommended ICU4J bundles will be in Orbit).
Use the most efficient message bundles
Projects should use Eclipse message bundles unless there are technical reasons not to, since (with or without translations) these are known to be more memory efficient that some other forms of handling UI-releated strings. This is important to Eclipse and adoption is some adopters end up using thousands of bundles ... so, that's a lot of strings!
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. This typically means the UI should be frozen by M6 (a "freeze" means all major changes and additions are done by M6, and changes after that are done in a controlled, well documented, well reviewed fashion, so Babel translators can more easily keep up with late changes). The project should use the Babel Pseudo Translation Test to verify their translatability. See bug 217339.
Enable development for all languages
Planning Council Exception Process
First, the Project's PMC must approve the request for an exception and it is the PMC (not the lone Project or committer) that makes the request to the Planning Council. The Planning Council member that represents the PMC is the one to bring the issue forward to the Planning Council.
Testing of Simultaneous Release Repository
Some of the items marked "(tested)" means that there is some degree of automatic checking and reporting done on the repository. The reports, for example, see the Luna Reports do not test "project by project" but as a whole, give some idea of where there are violations or problems. Ideally, the common repo tests should be a final sanity check, and projects can include their own automatic testing during their own build processes. See reporting FAQs for more information. Projects themselves (and/or adopters) are responsible for checking these reports ... that is, the Planning Council does not "police" compliance, the projects and PMCs do.
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.