Introduction

OpenSpecimen Suite is the next-generation tissue banking application which integrates the functionality of the existing caBIG™ TBPT (Tissue bank and pathology Tools). The tool will make it easier for researchers to locate and analyze tissue specimens for use in cancer research that is based on tissue, clinical, and genomic characteristics.Licensing

All OpenSpecimen source and pre-built binaries are provided under the <OpenSpecimen Open Source License>

The OpenSpecimen Community

The OpenSpecimen community exists primarily through discussion groups/forums, the <issue tracker> and, to a lesser extent, the source control repository. You are encouraged to contribute to the discussion and you can also help us to keep the effectiveness of the groups high by following and promoting the guidelines listed here.

Please Be Friendly

Showing courtesy and respect to others is a vital part of the OpenSpecimen culture, and we strongly encourage everyone participating in OpenSpecimen development to join us in accepting nothing less. There's never a reason to be antagonistic or dismissive toward anyone who is sincerely trying to contribute to a discussion.

Where to Discuss OpenSpecimen

Refer to the discussion groups/forums. Specifically the OpenSpecimen development forum.

How to Report a Bug

See <issue tracker> for details on how issues are reported and tracked for OpenSpecimen.

Working with the Code

If you want to get your hands dirty with the code inside OpenSpecimen, the <Community Code Contribution> is the right place to start. 

Testing

Testing is very important to maintaining the quality of OpenSpecimen. Unit Tests must be written for any new code, and changes must be verified to not break existing tests before they are submitted for code review. Please see sections below for a more detailed description of OpenSpecimen Testing approach.

Ensuring Code Quality

Please see the conventions described below.

Using an IDE

You may use any IDE (or even a simple text editor) to do OpenSpecimen development. Please refer to the <Community Code Contribution> document for details about setting up the Eclipse environment.

OpenSpecimen Architecture

The OpenSpecimen Technical Administration Guide describe the OpenSpecimen architecture. The guide focuses on administrative tasks associated with the use of OpenSpecimen Suite and mainly focuses on using the application program interface in the OpenSpecimen Suite application for data entry and query operations. New developers should read over the guide first to make sure they understand the big picture of OpenSpecimen development.

Contributing Code

As OpenSpecimen is open source, we're excited that to make it possible for our users to fix bugs and create new features, and we hope to get great patches from the community. Before you fire up your favorite IDE and begin hammering away at that new feature, though, please take the time to read this section and understand the process. While it seems rigorous, we want to keep a high standard of quality in the code base. Also, please be aware that the code contributors must sign a Contributor License Agreement before we can accept any code.

Code Style

To keep the source consistent, readable, diffable and easy to merge, we use a fairly rigid coding style, and all patches will be expected to conform to the style outlined here. To keep things as simple as possible, many of these style rules will be automatically verified by the caTissue build; style issues that can't be caught by the build system must be addressed during code review.

Conventions

Most of the conventions are described with the PMD and Checkstyle rulesets, as mentioned in the sections above, and are enforced by the build. As there are exceptions to every rule, you can override these PMD and Checkstyle rules with appropriate annotations in the code. If you do, be sure to document the reason in an adjacent comment.

We describe some of the key conventions explicitly below.

Comments and Javadoc

Every file must have a license header at the top, prefaced with a copyright notice. A package statement and import statements should follow, each block separated by a blank line. Next is the class or interface declaration. In the Javadoc comments, describe what the class or interface does. Include an _@author_ tag.

Each public method or constant must likewise have Javadoc describing what it does. For methods, this must include documenting the arguments, return values, and possible exceptions. Expectations of parameters, such as whether they can be null, should be documented. The javadoc should describe behavior for all combinations of inputs, paying particular attention to edge cases.

Within method bodies, comments should be used as needed to document blocks of code that are doing something tricky or complex. In general, strive for self-documenting code.

Every file should have a and copyright notice. A package statement and import statements should follow, each block separated by a blank line, followed by the class or interface declaration. Both the class and each public method or field must have Javadoc documenting it.

Class and Method Lengths

You should endeavor to keep classes and methods to a reasonable size, both in terms of total lines of code and of cyclomatic complexity (number of nested loops and conditionals). Methods should generally fit on a screen without having to scroll. When classes and methods begin to grow beyond this size, look to factor out helper classes and methods to keep their size acceptable.

Imports

"Star" imports are prohibited, as they make it difficult to determine where classes come from in a large codebase.

Static imports should be used sparingly and only for very common DSL-style operations whose provenance will generally be well-known. Some examples include JUnit _assert_ methods and Mockito methods in unit tests.

Member order

The order within a Java file be:

• License header
• Package declaration
• Imports (grouped as below; within each grouping, ordered alphabetically)** _java_ and _javax_ imports** other third-party library imports** caTissue imports
• Class declaration** static final constants** static initializers** fields** constructors** methods
  • nested classes

Acronyms and Names

Treat acronyms and abbreviations as words. The names are much more readable. This applies in the case where the acronym is the entire word as well.

Parameterized Types

Parameterized type names should be one capital letter. The exception is when there are multiple parameter types, and a short 2-3 letter name (e.g. ID) is more descriptive.

Formatting

The project includes Eclipse formatter rules that describe the caTissue formatting conventions. If you import the project into Eclipse, as described earlier, Eclipse will automatically be configured to enforce the formatting when you either manually format or save the file.

Below we describe explicitly some of the key formatting rules.

Indentation

We use 4-space indentation. The indentation should be done using spaces, not tabs - most IDEs have configuration options to ensure this.

Line Length and Wrapping

Each line of text in your code should be at most 120 characters long. Use linefeed characters to break lines (Unix-style).

Curly braces and code blocks

Any code block (for / while / if / etc) must be enclosed in curly braces, even if it is only a single line. The opening braces should be on the same line as the if / for / while.if (condition) {
doX();
doY();
{color:#000000}}

Example Java class

This example class illustrates the conventions and formatting rules described above./*

*caTissue LICENSE header
\*/

package gov.nci.nih.catissue;

import java.util.List;
import java.util.LinkedList;

import org.apache.commons.lang.StringUtils;

import gov.nih.nci.catissue.util.Utils;

/*\*
* Custom implementation of Stack specifically for integers, for enhanced performance.}
\*
* @author dkokotov
\*/
public class MyIntStack {
private final LinkedList fStack;

public MyIntStack() {        fStack = new LinkedList();    }

public int pop() {        return ((Integer) fStack.removeFirst()).intValue();    }

public void push(int elem) {        fStack.addFirst(new Integer(elem));    }

public boolean isEmpty() {        return fStack.isEmpty();    }

Testing

Tests are very important, and we require submissions that include them, adding new tests for new functionality or updating existing tests for bug fixes.

Tests for Java classes must be placed in a parallel source tree under test and the test class name must be suffixed with Test. For example:src/main/java/gov/nih/nci/catissue/Utils.java
src/test/java/gov/nih/nci/catissue/Utils.java

The use of the parallel test tree has two major advantages:

• You can do package scope testing (vs. a tests subpackage).
• There is a clear separation between production and test code making packaging easier.

There are a few different kinds of tests in caTissue

• Unit tests - Unit tests test each class or component in isolation. In a unit test, dependencies of a particular component are typically replaced with mock implementations. This makes it possible to isolate any errors in the component itself from possible errors in its dependencies, as well as be precise about the contract the component has with its dependencies. All caTissue classes are expected to be unit tested. For DAO layer classes, the unit tests are executed against an actual database. Some caTissue classes use the Mockito framework to set up mock implementations of dependencies, whereas others use manually coded mocks.

• Integration tests - Integration tests test a component together with real implementations of its dependencies, to ensure that the complete assembly works as intended. In caTissue, we create integration tests as required, when the behavior to be tested depends on the interplay of multiple components that would be difficult to emulate with mock implementations. A common example is behavior that is triggered on transaction boundary. Contributors should create or extend data sets if needed.

• API Tests - API tests ensure that the caTissue service API works according to its specifications. The tests are implemented using JUnit and are executed using a real deployment of caTissue to a JBoss container, against a pre-defined data set. Contributors should create or extend API tests if their contributions affect the API.

• Functional Tests - functional tests are executed against the UI of a running caTissue application deployed in a JBoss container, to ensure it meets the user stories specifying expected behavior. caTissue currently uses a mixture of Selenium, HPQC, Cucumber tests for this purpose. At present, we do not require contributors to write functional tests (though they are welcome to), and they are maintained collaboratively by Development and QA teams.

Submitting Contributions

If you have developed a new feature or a bug fix for caTissue, we welcome your contribution. This section describes the steps you should take to submit your contribution. There are three paths a contribution may take:

• Option A: the contribution will be incorporated into the core codebase and appear in a subsequent release. This is the preferred option and the path most contributions should take.
• Option B: the contribution will not be incorporated into the core codebase. It will be committed to a dedicated branch, and will be released as part of an unofficial alternative distribution created and hosted at the TBTT-KC.
• Option C: the contribution will not be incorporated into the core codebase. It will be committed to a dedicated branch, and will be released as an unofficial alternative distribution created, hosted and supported by the developer.

Options B and C exist for cases where the contribution does not fit the near-term goals of the project, and enables that contribution to still have a path to be made available to interested members of the community.

The first steps of the contribution process are common to all three options; after that, the paths for the contribution diverge.

Initial Common Steps

1. Approach the caTissue development/support team through the TBTT KC forum, the TBTT KC email address, or personal contact with the caTissue team to discuss the contribution.
2. If you do not yet have access to caTissue development infrastructure, we will assist you in setting this up with the help of the TBTT KC and NCI Systems team. This includes:
   1. Access to Issue tracker
   2. Access to Code Review Tool
   3. Write Access to a private branch in the Subversion Repository in the _branches/community_ area.
3. Discuss and agree on the user stor(ies) to be implemented or the bug(s) to be fixed, the license, and the support mechanism. A ticket must exist for the user story or bug in the issue tracker; if it does not yet, it should be created.
4. Work in the branch and communicate regularly with the caTissue team via the development discussion forums.
5. The contribution must comply with the code quality and testing requirements described in this document.
6. Once the contribution is ready, submit the patch through the Crucible peer review tool. A caTissue committer will work with you to determine which of the three options are appropriate for the contribution and guide it through the remaining steps.

Option A: contribution accepted into core codebase and official release

1. The caTissue committer assigned to your contribution will perform peer review on it and work with you to make any needed changes. This may result in follow-up submissions in the peer review tool. Depending on your availability, the committer may make the changes themselves.
2. Once the required changes are made, the committer will merge your contribution into the trunk or current feature branch.
3. From this point forward, the contribution is owned by the caTissue development team as a whole, and will follow standard caTissue processes for inclusion in the next official release.
4. The release notes for the caTissue release in which the contribution appears will highlight and attribute your contribution.
5. The caTissue development team and TBTT KC will provide support for the contribution in the same manner as other features of caTissue.

Option B: contribution maintained as an unofficial TBTT KC sponsored release

1. The caTissue committer assigned to your contribution will do a sanity-check on it, an abridged version of peer review, and will work with you to make any needed changes.
2. Once the sanity check is satisfied, the TBTT KC will create a custom caTissue release (including installers) based on the most recent release and including your contribution.
3. The TBTT KC will perform basic testing of the release to verify the new features or bug fixes.
4. The TBTT KC will work with you to develop materials for the custom release, including license terms, installation guide (if the custom release needs steps outside of regular caTissue installation), release notes, and possibly others.  Contributors contribution is required for creation of these documents.
5. The release will be hosted and advertised on the TBTT KC site. It will be advertised "as-is", but the TBTT KC will provide limited support, as resources permit.

Option C: contribution maintained as an unofficial developer-hosted release

1. The caTissue committer assigned to your contribution will do a sanity-check on it, an abridged version of peer review. It is up to you to incorporate any suggested changes.
2. It is then up to you to create and publish the release, and developing supporting materials, including license terms, installation guide (if the custom release needs steps outside of regular caTissue installation), release notes, and possibly others. The TBTT KC can advise you on creating these materials.
3. Likewise, it is up to you determine the level of support you will provide for the custom release.
4. The TBTT KC will announce and link to your custom release on their site. It will be advertised "as-is", and the TBTT KC will not provide any support for it.

Followup work on the contribution

Where warranted, we encourage you to continue working on the code in collaboration with the caTissue development team and continue to support the code.

caTissue Committers

The current members of the caTissue development team are the only committers at present. However, contributors can become committers by demonstrating a track record of high-quality submissions and community participation, as well as a sufficient time commitment to the project.

Contributor License Agreements

Before we can accept a patch from you, you must sign a Contributor License Agreement (CLA). The CLA protects you and us.

• If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an caTissuedoc:Individual CLA|pages/createpage.action?spaceKey=caArray2project&title=Individual+CLA&linkCreation=true&fromPageId=35754741|||||||||\.
• If you work for a company or research institution that wants to allow you to contribute your work to caArray, then you'll need to sign a caTissuedoc:Corporate CLA|pages/createpage.action?spaceKey=caArray2project&title=Corporate+CLA&linkCreation=true&fromPageId=35754741|||||||||\.
  Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it.