Child pages
  • Criteria for Provisional Status
Skip to end of metadata
Go to start of metadata

Old material archived for reference...

Sakai Community Practice [SCP:2.0]

Criteria for Provisional 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

Describe the criteria used to determine if a submitted tool should have provisional status in the next release of the Sakai Enterprise Bundle. Since distribution methods are likely to change over time, this document avoids defining how tools will be distributed in a provisional manner. It is also recognized that future changes may render obsolete the designation of tools as provisional.

Description

Sakai tools fall into one of three categories:

  1. Tools we're not comfortable with and don't know enough about. These reside in the Sakai contribution area (contrib) but receive no Sakai resources.
  2. Tools we're getting comfortable with. These tools are assigned provisional status and may receive some Sakai resources, QA, attention, etc.
  3. Tools we've been using and we're comfortable with. These tools get full Sakai support, regression testing, etc.

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

A provisional tool is defined as a tool that is included in a Sakai release but excluded from the list of tools presented to the user when they are configuring their site through site setup. A method is provided to allow provisional tools to be activated during the configuration process.

The release notes will clearly identify the list of tools that are considered provisional in nature. Part of the goal of including a provisional tool in a release is to promote the tool to full inclusion in the release in a 6-9 month timeframe after the tool has been used, tested, evaluated by a wider range of sites. However a provisional tool may be dropped back to contrib if it is clear that it will not become part of the full release. It should be made clear in the release notes that a provisional tool does not receive the same level of QA as official tools.

Criteria

Criteria for provisional tool status are grouped as follows:

  • Community Support
  • Technical Elements
  • Interaction and Visual Design
  • Desirable Elements

Community Support

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.

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).

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.

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.

The developer(s) of the tool must be willing to answer questions about their application on Sakai dev list.

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).

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

Technical Elements

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

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.

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.

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

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.

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.

The tool must fully work in a clustered Sakai application server environment.

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.

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.

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.

JVM Requirement from Steve Githens

One thing that's not explicity included in the Provisional Tools is what JVM language the tool has to be written in.

Two Cases are coming to mind:

a) 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.

b) Using Tools that have Java Sources generated from another language, examples including the *.java sources generated from Python sources.

While I'm pretty sure nothing like this would be considered anytime soon, it might be an issue in another year or two, especially if the wacky compilation processes are incorporated into Maven.

Interaction and Visual Design

The tool UI must look 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.

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.

UI components available in the Sakai library should be used where possible (e.g. wysiwyg editor, calendar, paging widget).

The application must support all of the browsers currently supported by Sakai including FireFox/Mozilla and Internet Explorer.

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.

Desirable Elements

These elements are challenging and are strongly encouraged in order to get an application beyond provisional status. Tool developers should consider these concepts in the design and implementation of their tools:

  • The tool is properly internationalized with all of its user-displayed strings derived from properties files.
  • The tool should be fully accessible and pass a Sakai accessibility review.
  • 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.
  • Creation of web services API for the tool. The authors should provide a web-service layer which sits on top of their API.
  • The tool should participate in the Sakai cross-site import and export if it persists business objects.
  • The tool should be inter-operable with other Sakai tools where appropriate.
  • The tool should generate event codes that are triggered minimally on new, revise, and delete actions on the basic objects created by the tool.
  • Hibernate is not required but if the tool is doing significant ORM, it should be done using Hibernate - the application should work with the current version of Hibernate used in the Sakai release.
  • 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, 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 provisional 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:

Version

Date

Contributors

Description of Change

1

2/3/06

Charles Severance

Copied from a document submitted the SCP-PWG.

2

3/9/06

Mark Norton

Document updated to reflect SCP discussion on 2/22/06

3

3/15/06

Anthony Whyte

Minor text revisions; typographical, syntactial/grammatical errors corrected.

  • No labels

10 Comments

  1. I would like to see the following moved from "Desirable Elements" to "Technical Elements":

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

    Without at least these events, we have no way of tracking what users are doing with the tools. This can make support and evaluation very difficult. The Usage Data Work Group is working to define what information all the stakeholders need about usage. The use cases there, in particular "find out who did what action" and "find out when that action was done" are particulary relevant for support.

  2. In the interests of avoiding bloat, should we consider how things get demoted as well as promoted?

  3. RE: "The developer(s) of the tool must commit to helping to develop test plans and specifications for the application."

    Shouldn't the developers already have a spec in place prior to developing and deploying in production sites? Could this be changed to provide a specification? It also might be helpful to circulate the spec for review and commenting by the Sakai community at an early stage of development.

  4. If the tools are supplied with Entity-Relationship Diagrams (ERD) that helps in understanding of the system and its components.

  5. This talks about Sakai tools, but we really should be saying "Sakai Applications". A "Tool" is the user interface part of an "Application". It would help if we used this language everywhere we can, and here's a fine place for it.

    From the "Technical Elements" sections:

    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.

    This is misleading. Each Application MUST put it's API into shared/lib. This is standard practice and not at all bad. It's other jars that we want to keep out of there.

    Under Desirable Elements, please, do not say it is desirable to use Hibernate. I'm not sure that we know it is even a good thing to use Hibernate, and one application's use of Hibernate makes no difference to it's qualifications as good for Sakai. I'd just leave that out.

    The overlap statement is interesting, but I think there's no harm in having completely separate tools that do the same thing - it gives the community choice. It is really up to the Sakai release designer to pick which tools are in a particular "bundle" - it's not like there is just one.

  6. Description:
    Probably already planned, but... it's worth expanding on what 'gets Sakai resources' definitely means and what it 'might' mean: what resources are afforded these app's and what resources are hopefully afforded given sufficient resources... This would be be the first place I would have seen such a list if it were here, so I think it would make it clearer for all involved. It would also serve as a 'carrot', of sorts, to follow this path.

    Community Support:
    I think there should be a documentation requirement that is some docs are co-hosted with those of all the other apps. This could be minimal in scope, link out, etc... but, with this requirement, as least some information is findable in the place where one would expect.

    Technical Elements:
    I may be mistaken but I think 'Sakai AutoDDL approach' refers to only one specific technical approach among others (um... just two total, that I know about) like using the Hibernate sessionfactory, which technically uses hbm2ddl. So unless AutoDDL is intended to subsume the hibernate method, this wording should be either more, or less, specific: eg, leaving out the first sentence, or using AutoDDL as an example.

    Security functions....now I really show my ignorance. I haven't done this yet in the app I am writing (I am just using security related API's directly).... it would help (me) if this document contained or linked directly to simple examples.

    Clustering.... again, examples of pitfalls....this is something that most will need to loop throuh QA, since a cluster may be hard to come by.

    Desireable Elements:
    'business rule code' and 'business object' access from other app's is a tall order and not necessarily appropriate since these monikers can cover more that I think this statement attributes to them. I think it better to leverage the notion of alternative implementations, hence refer to API abstraction, etc. And, maybe focus more on the 'service' notion and encourage developers to consider areas where other apps might want to interact..... this is usually a completely separate requirement set than what may have motivated the app's development in the first place.

    And to sort of piggyback on one of Glen's comments, the benefits of these things should be included here.... people need to infer that it is worth the effort, otherwise it is just dogma. There are benefits to using Hibernate, for example, it is not necessarily better to do so.

  7. Another point on this comment: "The developer(s) of the tool must commit to helping to develop test plans and specifications for the application."

    As the tool evolves, it is essential that the specifications be updated. As long as the specifications are updated, the TP's can be done as well.

  8. Technical elements:

    "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.

    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."

    Note that these two criteria are strictly in conflict - by Sakai Hibernate best practice, jars defining the data model of the application must be placed at a shared classloader level.

  9. Another "Community Support" requirement should be:

    Status and future plans for the tool must be tracked and regularly updated using Sakai's project coordination process.

  10. From QA-Release Meeting discussions on 14-Mar-2007:

    • Licensing requirement should explicitly mention need for Individual CLA an Organizational CCLA.
    • Production requirement should explicitly mention scalability factor, (i.e., in production at large institutions versus small institutions).