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
- documentation of a workflow
Prior to accepting a user contribution though are certain expectations that a contributor must fulfill. This is to ensure that contributions retain the 'correctness' of the default processing stream (its data output), that new data forms are worthy of inclusion (publishable), 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.
- 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 spanning a timeline of 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, should the contributor begin their work. It is expected that their wiki documentation will evolve and develop alongside their contribution.
The other primary expectation of a contributor is the inclusion of test code (if appropriate). 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 experiences of these contributions.
Author: Nick Schmansky