How to make a code contribution¶
This document outlines the process for contributing code to the Astropy project.
Already experienced with git? Contributed before? Jump right to Astropy Guidelines for git.
Before following the steps in this document you need:
Strongly Recommended, but not required¶
You cannot easily work on the development version of astropy in a python environment in which you also use the stable version. It can be done — but can only be done successfully if you always remember whether the development version or stable version is the active one.
Python virtual environments offer a better solution and take only a few minutes to set up. It is well worth your time.
Not sure what your first contribution should be? Take a look at the Astropy issue list and grab one labeled “package-novice”. These issues are the most accessible ones if you are not familiar with the Astropy source code. Issues labeled as “effort-low” are expected to take a few hours (at most) to address, while the “effort-medium” ones may take a few days. The developers are friendly and want you to help, so don’t be shy about asking questions on the astropy-dev mailing list.
If you have never used git or have limited experience with it, take a few minutes to look at these resources:
Double check your setup¶
Before going further, make sure you have set up astropy as described in Try the development version.
In a terminal window, change directory to the one containing your clone of
Astropy. Then, run
git remote; the output should look something like this:
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
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 # this is master in your local repo remotes/your-github-username/master # master on your fork of Astropy on GitHub remotes/astropy/master # the official development branch of Astropy
The naming scheme used by git will also be used here. A plain branch name,
master means a branch in your local copy of Astropy. A branch on a
astropy , is labeled by that remote,
This duplication of names can get very confusing for maintainers when trying
to merge code contributions into the official master branch,
astropy/master. As a result, you should never do any work in your master
master. Always work on a branch instead.
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
git fetchgets the latest development version of Astropy, which you will use as the basis for making your changes.
git branchmakes a logically separate copy of Astropy to keep track of your changes.
git addstages files you have changed or created for addition to git.
git commitadds your staged changes to the repository.
git pushcopies the changes you committed to GitHub
git statusto see a list of files that have been modified or created.
A good graphical interface to git makes some of these steps much easier. Some options are described in Get a git GUI (optional).
- Don’t use your
masterbranch 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 astropy (instructions are below).
- Name your branch for the purpose of the changes, for example
- Make frequent commits, and always include a commit message. Each commit should represent one logical set of changes.
- Ask on the astropy-dev mailing list if you get stuck.
- Never merge changes from
astropy/masterinto 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
- Name the remote that is the primary Astropy repository
astropy; in prior versions of this documentation it was referred to as
These, conceptually, are the steps you will follow in contributing to Astropy:
- Fetch the latest Astropy
- Make a new feature branch; you will make your changes on this branch.
- Install your branch
- Follow The editing workflow to write/edit/document/test code - make frequent, small commits.
- Add a changelog entry
- Copy your changes to GitHub
- From GitHub, Ask for your changes to be reviewed to let the Astropy maintainers know you have contributions to review.
- 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 Astropy issue is at Contributing code to Astropy, a worked example.
Fetch the latest Astropy¶
From time to time you should fetch the development version (i.e. Astropy
astropy/master) changes from GitHub:
git fetch astropy
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
astropy/master, and if there have been commits since
you last checked,
astropy/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
buxfix-for-issue-42 clearly describe the purpose of the branch.
Always make your branch from
astropy/master so that you are basing your
changes on the latest version of Astropy:
# Update the mirror of trunk git fetch astropy # Make new feature branch starting at astropy/master git branch my-new-feature astropy/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 Astropy maintainers on GitHub.
To connect your local branch to GitHub, you git push this new branch up to
your GitHub repo with the
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 Astropy.
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 astropy install and makes it very easy to recover from mistakes.
Once you have activated that environment you need to install the version of Astropy you are working on. Do that with:
python setup.py develop # typically python 2.x, not python 3
python3 setup.py install # python 3... # ...though python3 may be called python3.3 or just python, # depending on your system.
If you are using python 3 you will need to re-install after making changes to the Astropy source code. Re-installing goes much faster than the initial install because it typically does not require new compilation.
The editing workflow¶
Conceptually, you will:
- Make changes to one or more files and/or add a new file.
- Check that your changes do not break existing code.
- Add documentation to your code and, as appropriate, to the Astropy documentation.
- Ideally, also make sure your changes do not break the documentation.
- Add tests of the code you contribute.
- Commit your changes in git
- Repeat as necessary.
In more detail¶
Make some changes to one or more files. You should follow the Astropy Coding Guidelines. Each logical set of changes should be treated as one commit. For example, if you are fixing a known bug in Astropy and notice a different bug while implementing your fix, implement the fix to that new bug as a different set of changes.
Test that your changes do not lead to regressions, i.e. that your changes do not break existing code, by running the Astropy tests. You can run all of the Astropy tests from ipython with:
import astropy astropy.test()
If your change involves only a small part of Astropy, e.g. Time, you can run just those tests:
import astropy astropy.test(package='time')
Tests can also be run from the command line while in the package root directory, e.g.:
python setup.py test
To run the tests in only a single package, e.g. Time, you can do:
python setup.py test -P time
For more details on running tests, please see Testing Guidelines.
Make sure your code includes appropriate docstrings, described at Astropy Docstring Rules. If appropriate, as when you are adding a new feature, you should update the appropriate documentation in the
docsdirectory; a detailed description is in Writing Documentation.
If you have sphinx installed, you can also check that the documentation builds and looks correct by running, from the
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.)
If the build_docs command is not found, try running
python setup.py build_sphinxinstead.
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 Astropy, a worked example.
Stage your changes using
git addand commit them using
git commit. An example of doing that, based on the fix for an actual Astropy issue, is at Contributing code to Astropy, a worked example.
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.
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:
- ``astropy.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.
When writing changelog entries, do not attempt to make API reference links by using single-backticks. This is because the changelog (in its current format) runs for the history of the project, and API references you make today may not be valid in a future version of Astropy. However, use of double-backticks for monospace rendering of module/class/function/argument names and the like is encouraged.
Copy your changes to GitHub¶
This step is easy because of the way you created the feature branch. Just:
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 Astropy:
Go to the URL of your fork of Astropy, e.g.,
Use the ‘Switch Branches’ dropdown menu to select the branch with your changes:
Click on the ‘Pull request’ button:
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 Astropy may ask a pull request to be rebased or squashed in the process of reviewing a pull request for merging into the main Astropy master repository.
The decisions of when to request a squash or rebase are left to individual maintainers. These may be requested to reduce the number of visible commits saved in the repository history, or because of code changes in Astropy in the meantime. A rebase may be necessary to allow the Continious Integration tests to run. Both involve rewriting the git history, meaning that commit hashes will change, which is why you should do it only if asked.
Conceptually, rebasing means taking your changes and applying them to the latest version of the development branch of the official Astropy as though that was the version you had originally branched from. Each individual commit remains visible, but with new metadata/commit hashes. Squashing commits changes the metadata/commit hash, and also removes separate visibility of individual commits; a new commit and commit message will only contain a textual list of the earlier commits.
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
After altering the history, e.g. with
git rebase, a normal
is prevented, and a
git push --force will be required.
How to rebase¶
Behind the scenes, git is deleting the changes and branch you made, making the changes others made to the development branch of Astropy, then re-making your branch from the development branch and applying your changes to your branch.
The actual rebasing is usually easy:
git fetch astropy master # get the latest development astropy git rebase astropy/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.
How to squash¶
Typically we ask to squash when there was a fair amount of trial and error, but the final patch remains quite small, or when files were added and removed (especially binary files or files that should not remain in the repository) or if the number of commits in the history is disproportionate compared to the work being carried out (for example 30 commits gradually refining a final 10-line change). Conceptually this is equivalent to exporting the final diff from a feature branch, then starting a new branch and applying only that patch.
Many of us find that is it actually easiest to squash using rebase. In particular, you can rebase and squash within the existing branch using:
git fetch upstream git rebase -i upstream/master
The last command will open an editor with all your commits, allowing you to squash several commits together, rename them, etc. Helpfully, the file you are editing has the instructions on what to do.
How to push¶
git rebase you will still need to push your changes to
GitHub so that they are visible to others and the pull request can be
updated. Use of a simple
git push will be prevented because of the
changed history, and will need to be manually overridden using:
git push --force
If you run into any problems, do not hesitate to ask. A more detailed conceptual discussing of rebasing is at Rebasing on trunk.
Once the modifications and new git history are successfully pushed to GitHub you can delete any backup branches that may have been created:
git branch -D tmp