Best Practices

From Informatics

Contents 1 Defect Management 2 Coding Standards 3 System Tests 3.1 Quality assurance 4 Performance Tuning 4.1 Speed 4.1.1 Data Set and Environment 4.1.2 Coding 4.1.3 More 5 Preparation of Release for Production 5.1 Points to add 6 Setting the version information

Defect Management

Defect tracking and resolution in geWorkbench is managed through a local installation (click here to access) of the Mantis software. A Mantis account (which can be obtained by contacting the geWorkbench team) is needed in order to access the system, submit defect reports and check resolution status. Guest access is also available, using the credentials guest/guest.

• Reporting bugs.
• Commencing work on an assigned bug: set the value of the field "Development status" to "Active". This allows tracking who is actually working on what.
• Peer Code Review: Have the developer assigned to review your code do so.
• Communicating that a bug is fixed (and reviewed).
• Testing and closing bugs: When the original reporter receives the e-mail notification alerting them to the defect's status change, they should proceed to verify that the defect if indeed fixed; if this is not the case, the defect is reopened and sent back to the developer ("Status"="assigned"; "Resolution"="reopened"). If the fix in effective then the tester should:
  • Set the defect's "Development status" field to "Completed".
  • Set the defect's "Status" field to "closed" or "closed - pending docs". The latter value should be chosen in the defect's "Update documentation" field as a value of "Yes".
  • If Status = "closed - peding docs" the defect should be assigned to the documentation manager (Ken Smith).
• Updating documentation: For defects requiring updating end user documentation, the documentation manager will arrange for the proper pieces of documentation to be updated after the defect has been fixed and vrified. After all documentation changes are completed the documentation manager should:
  • Set the defect's "Status" field to "closed"
  • Assign the defect back to the developer the worked on the fix (this last step is necessary in order to keep track of who fixed what). No further action on the defect is needed.

Coding Standards

• First read this article on how to write unmaintainable code.
• Follow the group style guide which is advertised publicly here.
• If you are using eclipse, import the following template and style files (get these from one of the existing developers): (Download Here)
  • eclipse.magnet.templates.xml
    • template file - Window -> Preferences -> Java -> Editor -> Templates. Select Import and import the file eclipse.magnet.templates. Click Apply.
      • ap+Ctrl+spacebar - do this at the top of the file to get the license, copyright, institution (this is the preamble for a java file).
  • eclipse.magnet.code.style.xml
    • style file - Window -> Preferences -> Java -> Code Syle -> Formatter. Check Enable Project Specific Settings. Select Import and import eclipse.magnet.code.style. Click Apply.
      • Ctrl+Shift+f - this will format the java code according to the style.
      • Ctrl+Shift+o - this will organize the imports.
• We are proponents of Test Driven Development. If you are not, tell us why ... we would like to hear your argument. See JUnit for tips.
• If you create a new java file, make sure you add the following to the top of the file in the class level javadoc header:
  • @author <your name> - makes the file attributable
  • @version (dollar sign ... use the symbol)Id$ - the version number, timestamp, and the last person who edited the file will be added to the file (I did not use the initial dollar sign because twiki also interprets this and will place the versioning stamp here).
  • We are using commons logging as our logger. See Commons Logging for more information on configuration.
• Make sure to run geWorkbench with ant before checking your code into cvs:
  • For those of you using eclipse
    • Copy your geWorkbench directory under your eclipse workspace into another (clean) directory.
    • Replace the your component under geworkbench/component/<your component> with the one that has the latest changes.
  • cd to geworkbench directory
    • ant clean
    • ant run

System Tests

• See this section for Best practices (current procedures) on how set up for performing system tests. The system tests are implemented as MS Word documents that can communicate test results to a centralized database. Certain libraries and scripts have to be installed for this to work. All of this and where to find the test scripts will be described on the page linked here.

Quality assurance

• A work flow for ensuring the highest level of quality is described in the section Quality assurance procedures

Performance Tuning

Speed

We recommend the following for tuning the speed performance for a geWorkbench component:

Data Set and Environment

• Run a large data set through your component and note the behavior of the component. Insert timestamps before and after suspected trouble spots to pinpoint where the slowness occurs. These timestamps are also useful in verifying improved performance. Test files of all kinds are available in the Test File Collection Wiki.

• Understand the component usage profile as much as possible and set up your testing environment to mimic the user's. (For example, use the default memory allotment because the user will most likely not change his/her memory settings.)

• Take the user's worst case scenario and make it just a little worse. (For example, the user expects the component to display 20K genes. Test with 22K genes.)

• Also keep an eye on data accuracy. Make sure your component works correctly with the accuracy test files.

Coding

• Since majority of software users are used to significant startup time, pre-compute as much as possible during component initialization. Minimizing dynamic computation while the user is interacting with the component GUI.
• If there is no way to avoid significant computation time in the GUI, put up

1. Progress bar: If the computation may take several minutes, put up a progress bar to let the user know. Perhaps he/she would want a coffee/tea/water break.
2. Hourglass cursor: If the computation will take a few seconds (that is, it will be slow enough for the user to notice, but not so long to warrant a progress bar), turn the cursor into an hourglass to let the user know the component is still alive and working on his/her request.

• Whenever possible, avoid nested loops. Also be sure to check up your call stack to see if there are any loops up the chain. Even if your code uses a single loop (or no loops at all), a method a few steps up the stack may have nested loops. If the source code is not available to you, see if the documentation states how the method in question behaves.

• If memory and situation allow, store (intermediate) computational results if the on-the-fly calculations are time consuming. This can cut down on the recalculation time.

• If large data sets can potentially create an "out of memory" situation, please be sure to catch java.lang.OutOfMemoryError and notify the user.

More

• More tips are available in Java Performance Guidelines (pdf).

• Sorting a (large) collection of strings: Use collator keys.

Preparation of Release for Production

This section describes the process that should be followed when preparing a production release for geWorkbench. A number of development team roles are involved in various steps of the process. These roles are:

• Release Manager: Responsible for the overall release.
• Release Engineer: Responsible for CVS management.
• Tech Lead:
• Tester: Responsible for system testing designated functionality.
• Test Manager: Assigns scripts to Testers for testing.
• Technical Writer: Updates online help and tutorials section.

Role assignments should be listed within the release tracking pages.

The following steps are taken in order to prepare a release:

1. Task assignment: Specific team members are assigned the roles identified above. During the release preparation, each person is expected to perform the function associated with their assigned role.
2. Create release page: A dedicated page is created in order to keep track of all the release specific activities (see for example, GeWorkbench Release 1.6.2).
3. Identify components to be included in release: The release mananger (in collaboration with the tech lead) identifies which components will be included in the release. Not all components under the main development branch should necessarily be included in a production release. Some of them may contain code that is under active development; or they may lack proper end-user documentation. Further, given the large size of the geWorkbench download, it makes sense to try and reduce things as much as possible.
4. Edit file all_release.xml: The configuration file shipped with the production release is edited so that it contains only the components designated for inclusion in the release.
5. Create CVS branch for release: The release engineer creates a new CVS branch for performing testing and bug fixing. For simplicity, the full project is included in the branch. Release branches are named using the following convention:
   geworkbench_X_Y_Z
   where X = version major number, Y = version minor number, and Z = build number. An example branch name is:
   geworkbench_1_6_2.
6. Gene ontology files: make sure that the new branch contains the latest gene ontology (GO) file. We now use only the unified OBO format gene ontology file, not the three separate flat files used earlier.
7. Promoter - check the JASPAR website for any new release of motif data files. These go in the Promoter component source directory (for some reason, should probably fix that!).
   1. The URL is http://jaspar.genereg.net/html/DOWNLOAD/mySQL/JASPAR_CORE_2008/
   2. The two files used are:
      1. MATRIX_DATA.txt
      2. MATRIX_ANNOTATION.txt
8. Aracne: Make sure the new branch uses the latest version of Aracne. See Aracne-Java for information on how to create a jar from the source code. After creating this jar, place it in the geworkbench/components/aracne-java/lib directory.
9. Mindy: Make sure the new branch contains the latest version of Aracne and Mindy-Java. After creating these jars, place them in the geworkbench/components/mindy/lib directory.
10. Create/modify an Ant build script which creates a separate directory which will only contain the classes chosen for distribution. All should then be done on this distribution copy to make sure there are no unknown, hidden dependencies.
11. GenomeSpace: update and test the GenomeSpace launcher
12. Designate test cases to execute: The test manager in collaboration with the release manager identify test cases to be executed and assign them to testers. Test cases should (ideally) have associated test scripts.
13. Test case execution: Testers execute their assigned test cases. Errors are logged in the defect tracking system and resolved by developers. After a defect is fixed, the entire test case is re-executed. If a test script is incorrect (e.g., refers to GUI elements that do not exist any more) the test script is updated.
14. Verification of online help: The technical writer goes over all online help and verifies it is up to date.
15. Verification of tutorials: The technical writer goes over all tutorials and verifies that they are up to date.
16. Lessons learned: At the end of the release process a "lessons learned" section is added in the release page.

---

Points to add

1. Specify version numbers for each component that is part of the release (these are the component version numbers that users can see when selecting Help->Version from the main menu).
2. If need be, post a new version of the Javadocs API at http://wiki.c2b2.columbia.edu/workbench/api/.
3. If need be, prepare new version of SDK (enter detailed description of process to follow).
4. If need be, update the geWorkbenchLicense file that ships with the application to include references to additional libraries used.
5. Prepare release notes.
6. Prepare know issue section.
7. In addition to the class files, make sure that the distribution includes:
   1. Release notes.
   2. License text.
8. The last step of the release process should be the announcement of the new release at the geworkbench-announce and geworkbench-users mailing lists.

Setting the version information

The version number must be changed in the following files:

1. image file geWorkbenchsmall.png
2. InstallAnywhere project file geWrokbench.iap_xmp
3. version.txt
4. build.xml
5. application.properties