-
-
Notifications
You must be signed in to change notification settings - Fork 90
Creating a new release
There are a few parts to this:
- Check the list of contributors in
AUTHORS.rst - Check the changelog in
CHANGES.rst - A few commits/branches/tags to make in your local git repo.
- Tests of the branch/release to run on your personal fork of the repo on github.
- Commits to the main astropy repo for the project (or other "main" repo).
- Upload to pypi
The details of what you do depend a bit on whether you are releasing a major, minor or patch version.
Version numbers should be X.Y.Z, where X is the major version, Y is the minor version and Z is the patch version. Z may be omitted for the first release of a minor or major version (e.g. 0.2 instead of 0.2.0). Versions should follow, at least roughly, semantic versioning.
Development versions should have a version like X.Y.Z.dev; note that the . before dev is very important. Leave out that . and astropy_helpers will choke on anything it tries to do with the package.
For a DOI to automatically be issued, it must be turned on for this repository for you. Directions for how to do this are available here.
The current list of contributors is in AUTHORS.rst. You can check the git log for contributors since the last release with this (replace the starting version with the last release):
git shortlog -s -n v1.1.0..HEAD
The version specification part can be omitted if you want to see all of the contributors. These people are contributors to the Astropy package template but have not made separate contributions to ccdproc so we have not listed them in AUTHORS.rst:
- Thomas Robitaille
- Michael Droettboom
- Erik M. Bray
- Larry Bradley
- Wolfgang Kerzendorf
- Benjamin Alan Weaver
If the same person shows up twice in the log under slightly different names (e.g. Matt Craig vs Matthew Craig you can set which name is displayed in the short log by editing the .mailmap file.
The change log is in CHANGES.rst. It should contain any user-facing changes but should not contain any changes that are purely internal. A quick way to generate of list of the changes merged since the last release (assuming that all changes were introduced by merging pull requests, which should be the case) is:
git log --grep="Merge" v1.1.0..HEAD
If you are releasing a brand new major version (e.g. 1.0) or minor version (e.g. 0.2) for which there hasn't been a previous release the first step is to create a new commit on master with the version number for the release. That commit will also become the root of the branch for the release. Right after that you want another commit setting the version on master to the development version of whatever the new next major or minor version will be.
On the local master branch:
- Check that the lastest version of astropy_helpers is being used.
- Change
VERSIONinsetup.pyto the version number (e.g.0.2or1.0) - Edit the release date in
CHANGES.rstand - Commit this change to git.
- Tag commit with version number (e.g.
v0.2):git tag v0.2 - Change
VERSIONback to dev (e.g.0.3.devor1.1.dev)...do not forget the dot (.) beforedev! At the very least, the minor version number should increase by one. - Create branch named, e.g.
v0.2.x, on the commit tagged with the version number (e.g.0.2)
On your new version branch:
- Change the version number on that branch to, e.g.
v0.2.1.devorv1.0.1.dev - Commit that change to the version branch
If you are doing a patch release it is presumably because there are bugs you have fixed on master that are important enough to warrant fixing on a release you have already made. If the changes you want to introduce add new functionality or change the API you should do a major or minor release instead of a patch...take a look at semantic versioning for guidance.
The first time you do this you may want to try it on a temporary branch so that if something goes wrong you can just delete the temporary branch.
Identify the fixes you want to apply:
- If you have been tagging issues/pull requests in some consistent way (e.g. with the tag
affects-release) this isn't too hard...just filter for those pull requests on github. If you haven't been tagging you will need to dig through the commit history. - Either way, the commits from master that you want ot apply to the release are the merge commits for the issue/pull request you want to patch for. This allows you to apply the fix in a single commit.
- Check out the branch you are patching (e.g.
v0.2.x)) if you haven't yet. - The idea is to
git cherry-pickthe merge commits from master and apply them to the development branch. The only wrinkle has to do with tellinggitwhich of the two parents that went into the merge commit is the one to use for generating the difference that will be applied to fixing your version branch....much more detail below:
cherry-picking:
Turns out it isn't quite as simple as just doing a cherry-pick. The thing you want to cherry-pick is the merge commit made when the PR was accepted; in ccdproc, see, e.g. 26b6050, a commit I want to cherry-pick onto the 0.2.x branch. That merge commit has two parents, bb6ccbc (on master) and a60aa43 (on the PR). cherry-pick needs to know which of those two parents it should do a difference against to get the changes to be applied. To do that, use the -m option to cherry-pick. -m takes an argument indicating which parent you want...1 for the first, 2 for the second, etc. Determine which commit is the one you want by doing git show on the commit you want to cherry-pick.
To recap, given that I want to cherry-pick 26b6050:
$ git show 26b6050 # the merge commit I want to cherry-pick
commit 26b60502ca82f99e042a04771621e938bc3dc4f3
Merge: bb6ccbc a60aa43 # <============ this shows the parents, 1 is bb6ccbc (master), 2 is a60aa43
Author: Steve Crawford <[email protected]>
Date: Fri Aug 29 15:36:04 2014 +0200
Merge pull request #167 from mwcraig/new-meta
Fix a number of metadata-related issues with CCDData class
git cherry-pick -m 1 26b6050 # <======= the -m 1 selects master as the reference branchDone with cherry-picking? Next steps are:
- Push this updated branch to your github account and see if the tests pass.
- Edit the revision number in
setup.pyto, e.g.0.2.1 - Edit the release date in
CHANGES.rstand add a new section for the next patch release. - Commit this change.
- Tag that commit with the release number
- Edit the release number in
setup.pyto the development version, e.g.0.2.2.dev.
Check the author list for the ccdproc entry on ASCL and edit if appropriate.
Push the change to your github account:
- Push here first so that travis tests can run(you may need to configure a travis account to run on pushes to your fork...don't push to astropy without testing the changes first)
- Since these changes are not done as a pull request you really, really should test them on your fork first!
After tests pass push changes to the astropy github account:
- The details of this command depend on how you've set up github authentication.
- To push the changes on master:
git push -v --tags https://github.com/astropy/ccdproc.git master:master - To push the commits on the new branch (the
v0.2.xbranch in this example):git push -v --tags https://github.com/astropy/ccdproc.git v0.2.x:v0.2.x
Prior to doing this, check that the tar file will build appropriately and contains everything that you do want. So run:
python setup.py sdist
And then check the resultant tarfile.
Assuming you have already registered the project on pypi, doing a release is really easy:
python setup.py sdist upload
Prior to running this though, switch back to the commit that you have tagged for this release so that the version is set correctly in setup.py
Open a pull request at the conda-forge ccdproc feedstock updating the version and checksum.
You will need to log in to readthedocs.org, go to the project's administrative page, and, in the "Version" part of the settings, select the new release you've made to force it to be built.