### Navigation

- index
- modules |
- next |
- previous |
- Developer's Guide v6.4.1 »
- Sage Notebook Developer Guide »

# Making a Patch

You’ve discovered a bug or something else you want to change in Sage Notebook — excellent!

You’ve worked out a way to fix it — even better!

You want to tell us about it — best of all!

The easiest way is to make a patch or set of patches. Here we explain how.

Making a patch is simple and quick, but it is not part of our normal workflow. So if you are going to be doing anything more than a once-off patch one time, please consider following the Git for Development model instead. See especially the part about “pull requests” at The Editing Workflow.

## Making Patches

### Overview

    # tell git who you are
    git config --global user.email you@yourdomain.example.com
    git config --global user.name "Your Name Comes Here"
    # get the repository if you don't have it
    git clone git://github.com/sagemath/sagenb.git
    # make a branch for your patching
    cd sagenb
    git branch the-fix-im-thinking-of
    git checkout the-fix-im-thinking-of
    # hack, hack, hack
    # Tell git about any new files you've made
    git add somewhere/tests/test_my_bug.py
    # commit work in progress as you go
    git commit -am 'BF - added tests for Funny bug'
    # hack hack, hack
    git commit -am 'BF - added fix for Funny bug'
    # make the patch files
    git format-patch -M -C master

You may attach a short generated patch file to the Sage Notebook mailing list or better, open an issue at the Sage Notebook github site (see Git for Development) and cut and paste your patch in a comment there. In either case we will thank you warmly.

### In Detail

1. Tell git who you are so it can label the commits you’ve made:

       git config --global user.email you@yourdomain.example.com
       git config --global user.name "Your Name Comes Here"

2. If you don’t already have one, clone a copy of the Sage Notebook repository:

       git clone git://github.com/sagemath/sagenb.git
       cd sagenb

3. Make a ‘feature branch’. This will be where you work on your bug fix. It’s nice and safe and leaves you with access to an unmodified copy of the code in the main branch:

       git branch the-fix-im-thinking-of
       git checkout the-fix-im-thinking-of

4. Do some edits, and commit them as you go:

       # hack, hack, hack
       # Tell git about any new files you've made
       git add somewhere/tests/test_my_bug.py
       # commit work in progress as you go
       git commit -am 'BF - added tests for Funny bug'
       # hack hack, hack
       git commit -am 'BF - added fix for Funny bug'

   Note the `-am` options to `commit`. The `m` flag just signals that you’re going to type a message on the command line. The `a` flag — you can just take on faith — or see why the -a flag?.

5. When you have finished, check you have committed all your changes:

       git status

6. Finally, make your commits into patches. You want all the commits since you branched from the `master` branch:

       git format-patch -M -C master

   You will now have several files named for the commits:

       0001-BF-added-tests-for-Funny-bug.patch
       0002-BF-added-fix-for-Funny-bug.patch

   Although some projects would have you send these files to the Sage Notebook mailing list, we prefer submitting an issue request at the web interface to the Sage Notebook github page. See The Editing Workflow for how to create a “pull request” once you have created a Github account.

When you are done, to switch back to the main copy of the code, just return to the `master` branch:

    git checkout master

## Moving from Patching to Development

If you find you have done some patches, and you have one or more feature branches, you will probably want to switch to development mode. You can do this with the repository you have.

Fork the Sage Notebook repository on github — Making Your Own Copy (Fork) of Sage Notebook. Then:

    # checkout and refresh master branch from main repo
    git checkout master
    git pull origin master
    # rename pointer to main repository to 'upstream'
    git remote rename origin upstream
    # point your repo to default read / write to your fork on github
    git remote add origin git@github.com:your-user-name/sagenb.git
    # push up any branches you've made and want to keep
    git push origin the-fix-im-thinking-of

Then you can, if you want, follow the Development Workflow.

### Navigation

- index
- modules |
- next |
- previous |
- Developer's Guide v6.4.1 »
- Sage Notebook Developer Guide »