Differences between revisions 25 and 26
Deletions are marked like this. Additions are marked like this.
Line 11: Line 11:
The initial setup for contributing to the freesurfer repository involves the user forking off the freesurfer !GitHub repo, cloning the users fork into a local repository, then adding the freesurfer repository as an upstream remote. This setup illustrated below, followed by a more detailed description of the steps involved: The initial setup for contributing to the freesurfer repository involves the user forking off the freesurfer !GitHub repo, cloning the users fork into a local repository, then adding the freesurfer repository as an upstream remote. This setup is illustrated below, followed by a more detailed description of the steps involved:
Line 45: Line 45:
To contribute the the freesurfer code base, users should create branches off the {{{dev}}} branch, push the branch to their fork ({{{origin}}}), then submit '''Pull requests''' into {{{freesurfer/dev}}} to get those changes into the freesurfer code base. This workflow is illustrated below, followed by a more detailed description of the steps involved: To contribute the the freesurfer code base, users should create a new branch off the {{{dev}}} branch, push the branch to their fork ({{{origin}}}), then submit '''Pull requests''' into {{{freesurfer/dev}}} to get those changes into the freesurfer code base. This workflow is illustrated below, followed by a more detailed description of the steps involved:

Contents

  1. Initial Setup
  2. Committing Changes
    1. Cleanup steps (Optional)
  3. Developing
      1. Data files

The official freesurfer source code repository can be found on the page:

Initial Setup

The initial setup for contributing to the freesurfer repository involves the user forking off the freesurfer GitHub repo, cloning the users fork into a local repository, then adding the freesurfer repository as an upstream remote. This setup is illustrated below, followed by a more detailed description of the steps involved:

github_workflow6.jpeg

  1. Sign up for a github account if you don't already have one. When creating an account, you can use any email you want, but developers at the Martinos Center should eventually link their <username>@mgh.harvard.edu email to their GitHub account. This can be done after the account is created.

  2. From your GitHub account, fork the freesurfer project repository by clicking on the 'Fork' button near the top right-hand of the page. This creates a copy of the freesurfer code base under your account on the GitHub server.

    fork.jpeg

  3. On your local machine, make a clone of your freesurfer repository (the one you forked): 
    git clone git@github.com:<git_username>/freesurfer.git

  4. Add the main freesurfer repository as a remote to the local clone you already have on your local disk, and set it as the upstream remote: 

    git remote add upstream git@github.com:freesurfer/freesurfer.git
  5. Type the following command to make sure you have the proper setup: 
    git remote -v

origin  git@github.com:zkaufman/freesurfer.git (fetch)
origin  git@github.com:zkaufman/freesurfer.git (push)
upstream        git@github.com:freesurfer/freesurfer.git (fetch)
upstream        git@github.com:freesurfer/freesurfer.git (push)

Committing Changes

To contribute the the freesurfer code base, users should create a new branch off the dev branch, push the branch to their fork (origin), then submit Pull requests into freesurfer/dev to get those changes into the freesurfer code base. This workflow is illustrated below, followed by a more detailed description of the steps involved:

github_workflow5.JPG

  1. When you start to make changes, the first thing to do is make sure you are in the dev branch and everything is up to date with the upstream repo: 
    git branch

* dev
    git pull upstream dev

  2. Then create a new branch (off dev) to hold your work and start making changes. Ideally, use a prefix signaling the purpose of the branch: 

    git checkout -b nf-my-feature

    • nf- for new features

    • bf- for bug fixes

    • rf- for refactoring

    • doc- for documentations contributions.

    • test- for test related contributions.

  3. Work on this copy on your computer using Git to do the version control. When you're done editing, commit the files to the local branch and push the branch to origin (your personal GitHub account): 

    git add <modified_files>
git commit -m "Commit message"
git push origin nf-my-feature

  4. Finally, go to the GitHub web page of your fork of the freesurfer repo, and click Pull request to send your changes to the maintainers for review. Make sure you are submitting your newly created branch into the freesurfer/dev. This will send an email to the committers. You can commit new changes to this branch and keep pushing to your remote -- github automagically adds them to your previously opened Pull request.

    new_pull_request.JPG

    compare_changes.jpeg

Cleanup steps (Optional)

  1. Once your pull request is accepted (you should get an email), feel free to delete the branch you created: 
    git branch -D nf-my-feature

Developing

Instructions on how to further work with the freesurfer source code, including building, testing, and adding a binary to the tree, should consult the Freesurfer Developers Guide:

Data files

To be filled in later.