Guidelines on User Contributions

User contributions to the Freesurfer application are most welcome. The following are examples of contributions that could be made by users in the Freesurfer community:

With the exception of documentation contributions, a mechanism is needed to guide the integration of a user contribution into the open-source code base. This is to ensure that contributions retain the 'correctness' of the default processing stream (Freesurfer's data output), that new data forms are worthy of inclusion (leading to publishable research by the Freesurfer user community), that the contribution is maintainable over the course of several years, and that the contribution adheres to the licensing terms of the Freesurfer Software License. The primary expectation is the inclusion of documentation and tests, following the guidelines described next.

Before a user wishes to make a contribution, someone on the Freesurfer team should be contacted to determine initial interest on our part in the contribution. Contact can be made via the Freesurfer mailing list. Assuming worthiness of the contribution, the user should then create a Freesurfer wiki account, and begin to produce the following documentation on a wiki page:

Once the contributor supplies this documentation to the Freesurfer team, at least in a raw form, and once the Freesurfer team deems the documentation acceptable, the contributor enter a development phase, where access is granted to the code repository, following a process. That process is modeled after the one used in the VTK (Kitware Inc.) open-source project. It is based upon 'Git', a widely used distributed revision control system. The process is based on the 'branchy development workflow' documented in Git. It consists of three main steps:

Testing is of course a necessity, and occurs throughout the process. It starts with the test plan documentation submitted prior to project commencement, continues with development testing, then validation testing prior to code review and merging, and finally maintenance-phase testing involving automated regression tests run in the nightly build. The extent of this test code will vary depending on the complexity of the contribution, and most importantly, whether the contribution will affect the data output of Freesurfer's default processing stream. The test code should show that the contribution is functionally correct, is stable across OS platforms, and can be run in an automated fashion (for nightly regression testing).

Users in the Freesurfer community have made many valuable contributions in the past. Examples include a reworking of the vertex hash table mechanism (GW), a utility to improve the skull-strip (VZ,ZJ), a replacement of the Talairach alignment function (AS), a utility to create local gyrification surface maps (MS), and build environment improvements (PPJ, MH, YH). The guidelines just described have resulted from the positive experiences of these contributions.

Author: Nick Schmansky

UserContributionGuidelines (last edited 2012-02-08 16:03:41 by NickSchmansky)