University of Illinois · Graduate School of Library and Information Science · ISRL

music-ir.org || mirbib || IMIRSEL || M2K || modules || tools || MIREX

M2K (Music-to-Knowledge) Module Quality Assurance (QA) Plan

In order for each official release of M2K to be of consistent high quality, all IMIRSEL-released modules must be reviewed and pass this checklist. Future contributors will be asked to adhere to this if they wish to have their code included in upcoming official IMIRSEL M2K releases. Even those developers who wish to distribute their modules on their own would do the community a great service if they applied these recommendation to the modules they create.

You may wish to view a Conforming code sample.

When a module has passed all of the checks listed here, it will be ready for release:

• Code Compiles - before code is checked into the M2K repository a developer must ensure that the module builds. Checking in a module that does not compile will break the build and will cause trouble for all of the other developers. Those that break the build will be subject to public humiliation.
• Copyright header - the code must include the standard copyright header. The current IMIRSEL-release copyright header is: 

/*  * Copyright 2004  University of Illinois at Urbana-Champaign  * Portions Copyright 2004 University of East Anglia  * Portions Copyright 2004 Sun Microsystems Inc.  * Portions Copyright 2004 Any Other Organization that participated  *  * All Rights Reserved.  Use is subject to license terms.  * See the file "license.terms" for information on usage and  * redistribution of this file, and for a DISCLAIMER OF ALL  * WARRANTIES.  */

• Proper package - the code must be in one of the following Java packages (TBD is this the final package set?):

org.imirsel.m2k.discovery    org.imirsel.m2k.prediction    org.imirsel.m2k.transforms    org.imirsel.m2k.filters    org.imirsel.m2k.compute    org.imirsel.m2k.util    org.imirsel.m2k.prep    org.imirsel.m2k.vis    org.imirsel.m2k.io

• Source Code Formatting - Code should conform to Java coding conventions (See tools below).
• Source Code Documentation - Code should conform to the Javadoc commenting guidelines (See tools below).
• D2K Documentation - D2K has its own conventions for providing internal documentation that is used by the D2K environment. This documentation is important way to provide self-describing M2K modules. M2K modules should conform to the D2K Module Documentation conventions. Module documentation should include a description of the algorithm being implemented with a reference (where appropriate) to a literature resource for the algorithm.
• Code Review - each module should be reviewed by another programmer. The review should concentrate on functionality issues (i.e. answer the questions: how does the module work? is it implemented properly? are they any bugs?).
• Test - Each module must be tested before it can be released. Testing a module consists of the following steps:
  • Create a D2K Itinerary that uses the module.
  • Verify that the component info displays properly.
  • Verify that the component properties can be displayed and edited properly.
  • Verify that the component can be hooked up to other components.
  • Run the itinerary.
  • Verify that the component generates the proper outputs (either by a visualization module, observation of output, or an automated test).
  • Verify that when the itinerary is saved and reloaded the results are the same.
  • Verify that the module works properly when run on a grid (I'm not sure how to do this yet).
  • Document the test that was performed and the itinerary that was used so the test can be reproduced by others.

Tools that you can use

• Jalopy is a source code formatter for Java that will format Java code to meet the Java coding conventions (or pretty close).
• DocCheck reviews documentation comments, generating an HTML report that identifies empty comments and other omissions and irregularities in the documentation comments.