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.

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.

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 gitbranch-a you will see there are
three different branches called master:

*master# this is master in your local reporemotes/your-github-username/master# master on your fork of Astropy on GitHubremotes/astropy/master# the official development branch of Astropy

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 Astropy. A branch on a
remote, like astropy , is labeled by that remote, astropy/master.

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
branch, master. Always work on a branch instead.

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.

From time to time you should fetch the development version (i.e. Astropy
astropy/master) changes from GitHub:

gitfetchastropy

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.

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 astropy/master so that you are basing your
changes on the latest version of Astropy:

# Update the mirror of trunkgitfetchastropy# Make new feature branch starting at astropy/mastergitbranchmy-new-featureastropy/mastergitcheckoutmy-new-feature

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 --set-upstream option:

gitpush--set-upstreamyour-github-usernamemy-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 gitpush your changes to GitHub periodically. The
setup in this section will make that easier.

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

or:

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.

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:

importastropyastropy.test()

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

importastropyastropy.test(package='time')

Tests can also be run from the command line while in the package
root directory, e.g.:

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 docs directory;
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
astropy directory:

pythonsetup.pybuild_docs

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

Note

If the build_docs command is not found, try running pythonsetup.pybuild_sphinx instead.

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.

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 an entry to the file CHANGES.rst briefly describing the change you
made. Include the pull request number, too at the end of the entry. 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 you are opening a new pull request, you may not know its number yet, but you
can add it after you make the pull request. If you’re not sure where to
put the changelog entry, wait at least until a maintainer has reviewed your
PR and assigned it to a milestone.

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.

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.,
https://github.com/your-user-name/astropy.

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.

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.

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 Continuous
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:

gitbranchtmpmy-new-feature# make temporary branch--will be deleted later

After altering the history, e.g. with gitrebase, a normal gitpush
is prevented, and a gitpush--force will be required.

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:

gitfetchastropymaster# get the latest development astropygitrebaseastropy/mastermy-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.

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:

gitfetchupstreamgitrebase-iupstream/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.

After using gitrebase 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 gitpush will be prevented because of the
changed history, and will need to be manually overridden using:

gitpush--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: