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:
- bug fixes to source code
- enhancements to particular algorithms or functionality
- a utility producing a new data form
- build-stream improvements, such as new OS platform compatibility
- documentation:
- of a workflow
- a tutorial
- help text (in xml format)
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:
- Project Overview - a paragraph description of the contribution.
- Project Plan - a timeline and description of how the contribution will be developed and delivered, including details on any software licenses included in the contribution (especially if 3rd-party packages are used in development).
- Test Plan - a description of how the contribution will be tested prior to delivery, and how it will be tested by nightly regression tests.
User Guide - whether its a single function, set of functions, or a utility, one or more pages should describe how the end-user will use this contribution. A tutorial wiki page is essential for any large-scale new utility. This User Guide information should also find its way into the '--help' output if the contribution is a utility.
- Maintenance Plan - description of who will provide answers to end-user questions (whether the questions originate from the Freesurfer team, or from Freesurfer end-users) and how bug fixes will be resolved. A contributor is expected to provide support for their contribution for a few years.
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:
- local development (via a Git code checkout)
- a code review making use of Gerrit, which is a web-based code review system, facilitating online code reviews for projects using the Git version control system
- and concluding with the code integration step (code merging).
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