Skip to content

Standards

Jump to bottom
dankessler edited this page Jul 11, 2012 · 31 revisions

Hi everybody!

I'm hoping this page can document directly, or have links to pages, with documentation regarding coding standards that we all use.

Documentation Conventions

  • mcRoot is the stand-in for the top-level of the git work tree. For example, my git repository may live at ~/repos/MethodsCore, but Mike's might be at ~/gitstuff/Mike/MethodsCore. Throughout documentation (and even in some functions) we use mcRoot to refer to this path.

Matlab Conventions

Function Naming

Similar to how SPM does it, custom functions that we write that we anticipate being shared across packages should start with mc_. For example, mc_GenPath.m is used by a variety of our "central" scripts.

This scripts will live in mcRoot/matlabScripts/ and many of our functions will add this path.

Git Conventions

Repositories

There is one major repository, called universe throughout, though your alias for it may vary.

This repository is policed by group policy and review.

Each develop will also have his or her own repository. It is expected that users may freely fetch from this repository, but for the most part only the owner will ever push or write to it.

Branch Naming

All of these branches will live in universe

Repository-Level Branches

public This branch tracks currently released versions of the repository. It will update slowest.

develop This branch tracks work in progress. Features based on develop will affect the whole repository, or at least several toolboxes. Examples include changes to deployment hooks, large restructuring, etc.

releaseX.Y There will be several of these branches. Each time we are approaching a new release, we will start one of these branches.

Toolbox-Level Branches

Each "toolbox" will have its own set of branches. Let's use the svmbatch toolbox as an example throughout this document.

svmbatch_alpha Rapid iteration. This branch collects features when their developer believes that are reasonably ready to go. Pull requests to svmbatch_alpha should generally only require sign off of the feature's developer.

svmbatch_beta Semi-quick iteration. This branch periodically advances by merging in svmbatch_alpha. Pull requests to svmbatch_beta should only include svmbatch_alpha (or its parents, since it is a frequently moving target). Adoption of pull requests should get at least a +1 from two developers (the pull requester and one other developer). +1's don't necessarily indicate that the new code has been tested, but the diff has been reviewed and looks reasonable.

svmbatch_stable Slower iteration.

  1. This branch periodically advances by merging in svmbatch_beta. Pull requests to svmbatch_stable should only include svmbatch_alpha (or its parents, since it is a moving target). Adoption of pull requests should get at least a +1 from two developers (the pull requester and one other developer), but beyond just reading the diff they should actually test it.

  2. This branch also periodically advances by merging in develop. This way, any repository wide changes or bugfixes will make their way back to the toolbox branch

Branch/Merge Workflow

Developer Activities

If developing a new feature specific to one toolbox...

For this example, we'll be adding support for libsvm to svmbatch.

  1. Update your local repository from universe git fetch universe
  2. Base your new branch off of svmbatch_stable, and name it using toolbox/featurename syntax git checkout universe/svmbatch_stable -b svmbatch/libSVM_support
  3. Do work in your svmbatch/libSVM_support branch git commit -am "added support for libSVM"
  4. Perform some sort of testing or sanity check to make sure your code doesn't break anything in a really obvious way.
  5. Push your feature branch to your repository git push github/dankessler svmbatch/libSVM_support
  6. Submit pull request to merge your feature branch into svmbatch_alpha using github. Be careful to be sure that your request sets the Base Branch to UMPsychMethodsCore@svmbatch_alpha and NOT develop
  7. Write up some justification or explanation of what your feature does, and go ahead and adopt the pull request.

If developing a new feature that cuts across many toolboxes or affects core functionality

For this example, we'll be updating the deployment hooks for the whole repository

  1. Update your local repository from universe git fetch universe
  2. Base your new branch off of develop, and name it using core/featurename syntax `git checkout universe/develop -b core/deployment_hooks
  3. Do work in your core/deployment_hooks branch git commit -am "updated deployment hooks process"
  4. Perform some semi-rigorous testing to make sure you're not breaking anything.
  5. Push your feature branch to your repository git push github/dankessler core/deployment_hooks
  6. Submit pull request to merge your feature branch into develop using github. Your base branch will be UMPsychMethodsCore@develop, and your head branch will be dankessler@core/deployment_hooks
  7. Write up some justification or explanation of what your feature does, and ideally also mention which issue it addresses.
  8. Assign the pull request to somebody else. Allow discussion to follow. At least one other person should sign off on it, and they should have at least tested it.
  9. The assignee accepts the pull request, and develop is updated.

Repository Maintainer Activities

Clone this wiki locally