Developer Guidelines for SPM¶
These guidelines are designed to make it as easy as possible to get involved. If you have any questions that are not discussed in our documentation, or if it is difficult to find what you are looking for, please let us know by opening an issue.
Coding Style¶
In short the general formatting guidelines are:
- Use 4 spaces per indentation level, no tabs.
- Use whitespace to make the code more readable.
- No whitespace at the end of a line (trailing whitespace).
- Comments are good, especially when they explain the algorithm.
- Try to adhere to a 76 character line length limit.
- Use lower case with underscores for function names.
- Avoid padding brackets with spaces. For example,
spm_fcn(value)
is preferred overspm_fcn( value )
.
New functions should follow this overall format:
function [R1,...] = spm_fcn(P1,...)
% <- H1 line : Single line description using the imperative ->
% FORMAT [R1,...] = spm_fcn(P1,...)
%
% P1 - <-Argument/parameter description, including ranges->
%
% R1 - <-Description of returned values->
%__________________________________________________________________________
%
% HELP text
% Long description of function, including i/o details, algorithms and refs.
%__________________________________________________________________________
% AUTHOR
% Copyright (C) YEAR Wellcome Centre for Human Neuroimaging
%==========================================================================
% - B A N N E R S E C T I O N H E A D I N G
%==========================================================================
%-MAJOR section heading
%==========================================================================
%-MINOR section heading
%--------------------------------------------------------------------------
Pull Requests¶
Git recommendations for pull requests:
- Avoid working from the
main
branch of your fork, creating a new branch will make it easier ifspm
’smain
changes and you need to update your pull request. - Try to squash together small commits that make repeated changes to the same section of code so your pull request is easier to review, and
spm
’s history won’t have any broken intermediate commits. A reasonable number of separate well-factored commits is fine, especially for larger changes. - If any conflicts arise due to changes in
spm
’smain
, prefer updating your pull request branch withgit rebase
versusgit merge
orgit pull
, since the latter will introduce merge commits that clutter the git history with noise that makes your changes more difficult to review. - Descriptive commit messages are good.
- Using
git add -p
orgit add -i
can be useful to avoid accidentally committing unrelated changes. - GitHub does not send notifications when you push a new commit to a pull request, so please add a comment to the pull request thread to let reviewers know when you’ve made changes.
Merges¶
Git recommendations for pull request reviewers:
- When merging, we generally like
squash+merge
. Unless it is the rare case of a PR with carefully staged individual commits that you want in the history separately, in which casemerge
is acceptable, but usually prefersquash+merge
.