Sakai Community Practice [SCP:TBD]

Criteria for Supported Status

Recommendation Level: Required

This is a required practice.

Audience

This practice applies to developers and contributors who desire to have a tool distributed with the Sakai Enterprise Bundle.

Purpose

All Sakai tools fall into one of four categories: contributed, provisional, supported, and deprecated. This document describes the criteria required to be considered a full supported tool in Sakai. These tools are typically distributed fully exposed as part of the Sakai Enterprise Bundle. Many of the tools already included in the Enterprise Bundle do not meet the criteria set here. This document establishes the "gold standard" for tools and services. It does not determine if a tool is included in a particular distribution or not.

Description

As mentioned in the purpose above, Sakai tools fall into one of three categories:

This document outlines a set of technical criteria that an application must meet before being considered for inclusion in a Sakai release as a fully supported tool or service.|

A supported tool is defined as one that is included in a Sakai release and fully available for inclusion in sites using the site setup tool and other administration tools. A method is provided to allow fully supported tools to be de-activated during the configuration process, if desired.

Release documentation should identify the list of tools that are fully supported. However, not all Sakai tools currently included and fully exposed in distributions will meet the criteria set forth here. In part, this is due to raising the bar on what is required for all tools. The intent here is not to determine what should be included in the release or not. Rather, it is to establish goals of high quality in all Sakai tools. The inclusion of a tool in a distribution is not determined here.

Criteria

Criteria for supported tool status are grouped as follows:

• Community Support
• Technical Elements
• Interaction and Visual Design
• Internationalizaton
• Accessibility
• Interoperability
• Documentation
• Other Elements

Community Support

1.01 - Group of Committers
There must be an identified group of committers within the Sakai community who take responsibility for the tool. This group can be comprised of the original author(s) or others from the community willing to take responsibility for the application.

1.02 - Source Code Under Control
The application source code must reside in Sakai's source control system. Organization and management of the source control system is defined in a different Sakai Community Practice (to be determined).

1.03 - Two Sites Using Tool
At least two Sakai production sites must be utilizing the tool successfully in their production environments. Those sites should be able to report that the tool runs properly and is useful to their users. These sites must also report that the application does not cause any problems with other parts of the Sakai release such as poor performance, memory leaks, etc.

1.04 - Group of Maintainers
The developer(s) of the tool must be committed to maintaining the application across Sakai version changes including any necessary data conversion for their elements of Sakai if storage structure changes.

1.05 - Online Support and Question Answering
The developer(s) of the tool must be willing to answer questions about their application on Sakai dev list.

1.06 - QA Process Support
The developer(s) of the tool must commit to helping to develop test plans and specifications for the application. Until those test plans are in place, the author(s) will commit to join the Sakai release/QA process and perform the necessary QA on their application. To become an official tool, the author(s) of the tool must contribute test plans and specifications (to satisfy the requirements of the QA group).

1.07 - Bugs and Features Tracked
Bugs and feature requests for the tool must be tracked in Sakai's bug tracking system.

Technical Elements

2.01 - All Supported Databases Included
If the tool persists data to a database, it must support all official Sakai databases (currently HSQL, MySql, and Oracle).

2.02 - Support for Initialization of Database Tables
The tool must work properly with the Sakai AutoDDL approach. The application must properly create tables when tables do not exist and the tables must be named so as not to conflict with other Sakai tables.

2.03 - Access to Data Through Published APIs
All database access to tables that the tool does not own will take place via published Sakai APIs provided by the application that manages those tables. The tool should use APIs for access to its own data, but it must use APIs for access to data from others.

2.04 - Participate in System Configuration
The tool must participate in the system-wide configuration (sakai.properties) and not require any local configuration to be hand-edited.

2.05 - Participate in Sakai Security
The tool must properly operate in the Sakai Authorization and tool placement structure. It must either use existing appropriate security functions or introduce new security functions for the application.

2.06 - Independent of Patches to Other Tools
The tool will not require patches to other Sakai tools or to the Sakai framework. A application may require changes to other areas of Sakai, but those changes should be negotiated ahead of time and should be part of the full distribution.

2.07 - Work in a Clustered Server Environment
The tool must fully work in a clustered Sakai application server environment.

2.08 - No New JARS in Shared or Common
The tool cannot force new jars into shared/lib or common/lib. Sakai's goal is to keep these jar footprints as small as possible. Any new jar requirement in those areas requires significant discussion.

2.09 - Use Standard Versions of Shared Technologies
There are a number of system-wide elements in Sakai including Spring, Hibernate, and others--the application must work with the versions of these elements that are part of the Sakai release.

2.10 - Adherence to Sakai Licensing Policies
Licensing must be clean before the application is moved into Sakai's source control system and put into a Sakai distribution. The license must not violate the policies set by the Sakai Foundation. This also means that a tool cannot require other application or jar with a proprietary or ECL-incompatible license to be part of the distribution.

2.11 - Source Code Language
At this time, all fully supported Sakai tools must be written such that they will operate in a Java 1.5 run time environment. Tools adapted from other languages, such as Perl, PHP, Python, Ruby, etc., may be integrated using one of the tool adaptors, such as IMS Tool Interoperability or LinkTool.
Tools may also be developed in non-Java langauges such that they can either be compiled to Java byte code or executed via an interpreter that runs in Java. These cases include:

1. Using Tools that are either entirely written in another language (like BeanShell, Python, Ruby) and compiled to Java Bytecode, or have parts that have been written in another language and compiled down to jars or class files.
2. Using Tools that have Java Sources generated from another language, examples including the *.java sources generated from Python sources.

Interaction and Visual Design

3.01 - Adhere to Sakai Look and Feel
The tool UI must look and operate like the rest of the Sakai application and properly inherit skins from Sakai (i.e. when the sites color changes the tool colors change as well). The tool should not look "out of place" amongst other Sakai tools.

3.02 - Follow the Sakai Style Guide
The tool should follow general interaction guidelines outlined in the Sakai Style Guide (SG) so users have consistent experiences and expectations about how to complete actions such as "paging in a list", "navigating between pages", "taking action of items in a list", etc. across tools. The SG is a guide and should be used to help inform interaction decisions but is not meant to have all the answers. Additional information on tool style and functionality can be found in the Sakai Design Patterns section in Confluence.

3.03 - Use Available Sakai Components Where Available
UI components available in the Sakai library should be used where possible (e.g. wysiwyg editor, calendar, paging widget).

3.04 - Support Established Web Browsers
The application must support all of the browsers currently supported by Sakai including FireFox/Mozilla and Internet Explorer.

3.05 - Help System Support
The tool should provide basic help which integrates seamlessly with the Sakai Help system. The help should have a look and feel and writing style similar to the other elements of help.

Internationalization

4.01 - Two Byte Characters
Sakai tools shall provide support for UTF-8 byte character codes of one to four bytes.

4.02 - External Strings for Translation
The tool shall externalize all strings into property files where they maybe translated into langauges supported by Sakai.

4.03 - Support for International Dates
Display of dates shall be shown according to conventions established by the locale code.

4.04 - Support for International Numbers
Display of numbers shall be shown according to conventions established by the locale code.

4.05 - Support for International Currency
Display of monetary figures shall be shown according to conventions established by locale code.

4.06 - Support for Right to Left
Sakai tools shall provide support for the display of textual information intended to be read from right to left, as well as the more typical left to right. This can be accomplished by adhering to the standard Sakai style sheets. Gadgets that provide text editing capabilities should support entry and editing on a right to left basis.

4.07 - Editing in Other Languages
Sakai tools that provide editing capability shall also provide support for entry of two byte characters, accented characters, and international character entry techniques.

4.08 - Support for Variant subject/verb/object Ordering
All dynamically constructed phrases must be sensitive to locale specific subject/verb/object ordering by using the Sakai ResourceLoader class, currently: org.sakaiproject.util.ResourceLoader.getFormattedMessage().

4.09 - Support for Dynamic Language Preferences
All externalized strings should be referenced using the user's preferred language/locale, by using the Sakai ResourceLoader class, currently org.sakaiproject.util.ResourceLoader. The java.util.ResourceBundle class should not be used.

Accessibility

The tool must be accessible according to Section 508 Requirements and WCAG 1.0 Priority One and Two Criteria. Examples of this level of accessibility include, but are not limited to:

5.01 - Tool Fully Accessible
The tool should be fully accessible using a keyboard only (i.e., no mouse) and pass a Sakai accessibility review. See the Sakai 2.3 Evaluation Criteria for details.

5.02 - Use of ALT on Images
Tools that display images should include ALT text to appropriately describe the image content.

5.03 - Navigation Bars Accessible
Navigation bars and menus should use UL and LI tags to denote entries.

5.04 - Form Controls Accessible
All INPUT and TEXTAREA controls should include a LABEL parameter to identify the function and purpose of the control.

5.05 - Change in Language Noted
Changes in content language should be identified by a LANG or XML:LANG attribute.

5.06 - Data Tables Accessible
Data tables should include a CAPTION to label the table and SUMMARY to summarize the table contents.

5.07 - List of Data Accessible
Lists of content should be marked up using UL, OL, or DL lists.

5.08 - Frames Labeled
All frames should have a readable TITLE attribute.

5.09 - Content Flows on Font Change
Content should flow correctly when font sizes are changed.

5.10 - Color Not Used for Information
Color should not be used to convey information.

5.11 - Content Styled with Stylesheets
All content should be styled using style sheets, preferrably those provided by Sakai.

5.12 - All Functions Operated through Keyboard Commands
All functions, commands, buttons, and links should be accessible and executable using keyboard key sequences.

5.13 - Frequently Used Functions as Shortcuts
Frequently used functions should have keyboard shortcuts.

5.14 - Animation Controls
Animations and other automatically sequenced changes in content can be paused and restarted under user control.

5.15 - Tool Content Test for Assistive Devices
Tool content should be tested against screen readers (such as JAWS and Window-Eyes), screen enlargers (such as ZoomText and Kurzweil), braille displays and other assistive technology devices.

5.16 - Time Out Management
Tool should permit user to establish the length of their session prior to being timed out.

5.17 - Notification
Tool must notify user of impending changes to the document (such as timing out) and confirm when changes have occurred .

Interoperability

6.01 - Create Application Services
If the tool has any persistence or business rule code it should be factored into a Sakai Component with a published API which has complete javaDoc. This component should be designed so as to allow other applications and/or system processes to be able to work with the business objects handled by the application.

6.02 - Support Web Services
Creation of web services API for the tool. The authors should provide a web-service layer which sits on top of their API.

6.03 - Support for Import, Export, and Archiving
The tool should participate in the Sakai cross-site import and export, and archiving, if it persists business objects.

6.04 - Tool Integration
The tool should be integrated with other Sakai tools where appropriate. Access to data managed by other tools shall be done via APIs published by those tools.

Documentation

7.01 - Documentation for Use, Installation, Customization, and Administration
All support Sakai tools must provide documentation that describes basic use, installation, customization, and administration.

7.02 - Help Content
Sakai tools must provide help documentation in a form that may be integrated into the Sakai contextual help system.

7.03 - Optional Functional Requirements
Sakai tools may optionally describe the functional requirements currently supported.

7.04 - Test Plan
Sakai tools must describe a test plan for testing its capabilities. Team leads are encouraged to work with the QA-WG to communicate changes using their project status page and keep test plans current as the tool evolves.

7.05 - Project Sites
The Community Support requirements above specify that tools are supported by a Sakai project. Ideally, this project will have a web site on collab.sakaiproject.org or a Sakai Confluence site that provides additional technical documentation such as design documents, discussions, plans and roadmaps, etc..

Other Elements

8.01 - Event Logging
The tool should generate event codes that are triggered minimally on new, revise, and delete actions on the basic objects created by the tool.

8.02 - Minimize Overlap in Functionality

• In order for Sakai to seen to be a seamless application, effort needs to be made to minimize overlap in functionality with other Sakai "bundled" tools. At times, as tools are evolving, or complete replacement tools are being produced, overlap is acceptable. Where overlap will happen between tools under consideration, developers should first look to fixing/improving the existing tools rather than simply writing a new tool with a few features. Each tool which adds overlap may result in the long term need to "clean up" the overlap to maintain a good user experience.

Notification and Process

If an application element is being considered for inclusion as a fully supported tool, it should be ready for inclusion 30 days before the code freeze for that release. There should be an announcement to the community 30 days before the release code freeze so that the community can download, install, and evaluate the tool and comment on its suitability for inclusion.

The notification should include the following:

1. What is is
2. How to install / configure it
3. Known issues
4. Whom to contact

Inclusion of a supported tool will be based on input from the Sakai community to the current release team (to be described in a separate practice). Once the application is selected for inclusion, the developers must coordinate with the release team to update any install/release documentation.

Document History

All major changes should be recorded in the following history table: