How to make a code contribution

This document outlines the process for contributing code to the Scikit-beam project.

Already experienced with git? Contributed before? Jump right to Scikit-beam Guidelines for git.

Pre-requisites

Before following the steps in this document you need:

  • an account on GitHub

  • a local copy of the scikit-beam source. Instructions for doing that, including the basics you need for setting up git and GitHub, are at Try the development version.

New to git?

Some git resources

If you have never used git or have limited experience with it, take a few minutes to look at these resources:

In practice, you need only a handful of git commands to make contributions to Scikit-beam. There is a more extensive list of Git resources if you want more background.

Double check your setup

Before going further, make sure you have set up scikit-beam as described in Try the development version.

In a terminal window, change directory to the one containing your clone of Scikit-beam. Then, run git remote; the output should look something like this:

your-github-username
scikit-beam

If that works, also run git fetch --all. If it runs without errors then your installation is working and you have a complete list of all branches in your clone, your-github-username and scikit-beam.

About names in git

git is designed to be a distributed version control system. Each clone of a repository is, itself, a repository. That can lead to some confusion, especially for the branch called master. If you list all of the branches your clone of git knows about with git branch -a you will see there are three different branches called master:

* master                              # this is master in your local repo
remotes/your-github-username/master   # master on your fork of Scikit-beam on GitHub
remotes/scikit-beam/master                # the official development branch of Scikit-beam

The naming scheme used by git will also be used here. A plain branch name, like master means a branch in your local copy of Scikit-beam. A branch on a remote, like scikit-beam , is labeled by that remote, scikit-beam/master.

This duplication of names can get very confusing for maintainers when trying to merge code contributions into the official master branch, scikit-beam/master. As a result, you should never do any work in your master branch, master. Always work on a branch instead.

Essential git commands

A full git tutorial is beyond the scope of this document but this list describes the few git commands you are likely to encounter in contributing to Scikit-beam:

  • git fetch gets the latest development version of Scikit-beam, which you will use as the basis for making your changes.

  • git branch makes a logically separate copy of Scikit-beam to keep track of your changes.

  • git add stages files you have changed or created for addition to git.

  • git commit adds your staged changes to the repository.

  • git push copies the changes you committed to GitHub

  • git status to see a list of files that have been modified or created.

Note

A good graphical interface to git makes some of these steps much easier. Some options are described in Get a git GUI (optional).

If something goes wrong

git provides a number of ways to recover from errors. If you end up making a git mistake, do not hesitate to ask for help. An additional resource that walks you through recovering from git mistakes is the git choose-your-own-adventure.

Scikit-beam Guidelines for git

  • Don’t use your master branch for anything.

  • Make a new branch, called a feature branch, for each separable set of changes: “one task, one branch” (ipython git workflow).

  • Start that new feature branch from the most current development version of scikit-beam (instructions are below).

  • Name your branch for the purpose of the changes, for example bugfix-for-issue-14 or refactor-database-code.

  • Make frequent commits, and always include a commit message. Each commit should represent one logical set of changes.

  • Never merge changes from scikit-beam/master into your feature branch. If changes in the development version require changes to our code you can Rebase, but only if asked.

In addition there are a couple of git naming conventions used in this document:

  • Change the name of the remote origin to your-github-username.

  • Name the remote that is the primary Scikit-beam repository scikit-beam.

Workflow

These, conceptually, are the steps you will follow in contributing to Scikit-beam:

  1. Fetch the latest Scikit-beam

  2. Make a new feature branch; you will make your changes on this branch.

  3. Install your branch

  4. Follow The editing workflow to write/edit/document/test code - make frequent, small commits.

  5. Add a changelog entry

  6. Copy your changes to GitHub

  7. From GitHub, Ask for your changes to be reviewed to let the Scikit-beam maintainers know you have contributions to review.

  8. Revise and push as necessary in response to comments on the pull request. Pushing those changes to GitHub automatically updates the pull request.

This way of working helps to keep work well organized, with readable history. This in turn makes it easier for project maintainers (that might be you) to see what you’ve done, and why you did it.

A worked example that follows these steps for fixing an Scikit-beam issue is at Contributing code to Scikit-beam, a worked example.

Some additional topics related to git are in Some other things you might want to do.

Fetch the latest Scikit-beam

From time to time you should fetch the development version (i.e. Scikit-beam scikit-beam/master) changes from GitHub:

git fetch scikit-beam

This will pull down any commits you don’t have, and set the remote branches to point to the latest commit. For example, ‘trunk’ is the branch referred to by scikit-beam/master, and if there have been commits since you last checked, scikit-beam/master will change after you do the fetch.

Make a new feature branch

Make the new branch

When you are ready to make some changes to the code, you should start a new branch. Branches that are for a collection of related edits are often called ‘feature branches’.

Making a new branch for each set of related changes will make it easier for someone reviewing your branch to see what you are doing.

Choose an informative name for the branch to remind yourself and the rest of us what the changes in the branch are for. Branch names like add-ability-to-fly or buxfix-for-issue-42 clearly describe the purpose of the branch.

Always make your branch from scikit-beam/master so that you are basing your changes on the latest version of Scikit-beam:

# Update the mirror of trunk
git fetch scikit-beam

# Make new feature branch starting at scikit-beam/master
git branch my-new-feature scikit-beam/master
git checkout my-new-feature

Connect the branch to GitHub

At this point you have made and checked out a new branch, but git does not know it should be connected to your fork on GitHub. You need that connection for your proposed changes to be managed by the Scikit-beam maintainers on GitHub.

To connect your local branch to GitHub, you git push this new branch up to your GitHub repo with the --set-upstream option:

git push --set-upstream your-github-username my-new-feature

From now on git will know that my-new-feature is related to the your-github-username/my-new-feature branch in your GitHub fork of Scikit-beam.

You will still need to git push your changes to GitHub periodically. The setup in this section will make that easier.

Install your branch

Ideally you should set up a python virtual environment just for this fix; instructions for doing to are at Python virtual environments. Doing so ensures you will not corrupt your main scikit-beam install and makes it very easy to recover from mistakes.

Once you have activated that environment you need to install the version of Scikit-beam you are working on. Do that with:

python setup.py develop

The editing workflow

Conceptually, you will:

  1. Make changes to one or more files and/or add a new file.

  2. Check that your changes do not break existing code.

  3. Add documentation to your code and, as appropriate, to the Scikit-beam documentation.

  4. Ideally, also make sure your changes do not break the documentation.

  5. Add tests of the code you contribute.

  6. Commit your changes in git

  7. Repeat as necessary.

In more detail

  1. Make some changes to one or more files. You should follow the Scikit-beam Coding Guidelines. Each logical set of changes should be treated as one commit. For example, if you are fixing a known bug in Scikit-beam and notice a different bug while implementing your fix, implement the fix to that new bug as a different set of changes.

  2. Test that your changes do not lead to regressions, i.e. that your changes do not break existing code, by running the Scikit-beam tests. You can run all of the Scikit-beam tests from ipython with:

    import scikit-beam
scikit-beam.test()

    If your change involves only a small part of Scikit-beam, e.g. Time, you can run just those tests:

    import scikit-beam
scikit-beam.test('time')

  3. Make sure your code includes appropriate docstrings, described at Scikit-beam Docstring Rules. If appropriate, as when you are adding a new feature, you should update the appropriate documentation in the docs directory; a detailed description is in Writing Documentation.

  4. If you have sphinx installed, you can also check that the documentation builds and looks correct by running, from the scikit-beam directory:

    python setup.py build_docs

    The last line should just state build succeeded, and should not mention any warnings. (For more details, see Writing Documentation.)

    Note

    If the build_docs command is not found, try running python setup.py build_sphinx instead.

  5. Add tests of your new code, if appropriate. Some changes (e.g. to documentation) do not need tests. Detailed instructions are at Testing Guidelines, but if you have no experience writing tests or with the py.test testing framework submit your changes without adding tests, but mention in the pull request that you have not written tests. An example of writing a test is in Contributing code to Scikit-beam, a worked example.

  6. Stage your changes using git add and commit them using git commit. An example of doing that, based on the fix for an actual Scikit-beam issue, is at Contributing code to Scikit-beam, a worked example.

    Note

    Make your git commit messages short and descriptive. If a commit fixes an issue, include, on the second or later line of the commit message, the issue number in the commit message, like this: Closes #123. Doing so will automatically close the issue when the pull request is accepted.

  7. Some modifications require more than one commit; if in doubt, break your changes into a few, smaller, commits rather than one large commit that does many things at once. Repeat the steps above as necessary!

Add a changelog entry

Add an entry to the file CHANGES.rst briefly describing the change you made. Include the pull request number if the change fixes an issue. An example entry, for the changes which fixed issue 1845, is:

- `scikit-beam.wcs.Wcs.printwcs` will no longer warn that `cdelt` is
  being ignored when none was present in the FITS file. [#1845]

If the change is a new feature, rather than an existing issue, you will not be able to put in the issue number until after you make the pull request.

Copy your changes to GitHub

This step is easy because of the way you created the feature branch. Just:

git push

Ask for your changes to be reviewed

A pull request on GitHub is a request to merge the changes you have made into another repository.

When you are ready to ask for someone to review your code and consider merging it into Scikit-beam:

  1. Go to the URL of your fork of Scikit-beam, e.g., https://github.com/your-user-name/scikit-beam.

  2. Use the ‘Switch Branches’ dropdown menu to select the branch with your changes:

    ../../_images/branch_dropdown.png

  3. Click on the ‘Pull request’ button:

    ../../_images/pull_button.png

    Enter a title for the set of changes, and some explanation of what you’ve done. If there is anything you’d like particular attention for, like a complicated change or some code you are not happy with, add the details here.

    If you don’t think your request is ready to be merged, just say so in your pull request message. This is still a good way to start a preliminary code review.

Revise and push as necessary

You may be asked to make changes in the discussion of the pull request. Make those changes in your local copy, commit them to your local repo and push them to GitHub. GitHub will automatically update your pull request.

Rebase, but only if asked

Sometimes the maintainers of Scikit-beam will ask you to rebase your changes before they are merged into the main Scikit-beam repository.

Conceptually, rebasing means taking your changes and applying them to the latest version of the development branch of the official scikit-beam as though that was the version you had originally branched from.

Behind the scenes, git is deleting the changes and branch you made, making the changes others made to the development branch of Scikit-beam, then re-making your branch from the development branch and applying your changes to your branch. This results in re-writing the history of commits, which is why you should do it only if asked.

It is easier to make mistakes rebasing than other areas of git, so before you start make a branch to serve as a backup copy of your work:

git branch tmp my-new-feature # make temporary branch--will be deleted later

The actual rebasing is usually easy:

git fetch scikit-beam/master  # get the latest development scikit-beam
git rebase scikit-beam/master my-new-feature

You are more likely to run into conflicts here–places where the changes you made conflict with changes that someone else made–than anywhere else. Ask for help if you need it.

After the rebase you need to push your changes to GitHub; you will need force the push because git objects to re-writing the history of the repository after you have pushed it somewhere:

git push -f

If you run into any problems, do not hesitate to ask. A more detailed conceptual discussing of rebasing is at Rebasing on trunk.

Once your rebase is successfully pushed to GitHub you can delete the backup branch you made:

git branch -D tmp