Skip to content

Creating a new release

Jump to bottom Edit New page
Matt Craig edited this page Dec 21, 2021 · 25 revisions

How to do a release of ccdproc

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.
  • [optional, if possible] 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.

About version numbering

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 should be included for even first release of a minor or major version when it will be 0 (e.g. 0.2.0 instead of 0.2). 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.

  • Version numbers in tags should not contain a leading v.
  • Version numbers should always include all three number (e.g. 2.3.0 not 2.3, and 3.0.0 not 3 or 3.1.

Zenodo DOI

For a DOI to automatically be issued, it must be turned on for this repository for you AND you have to do a github release. Simply making a new tag will not trigger creation of the Zenodo entry. Directions for how to do this are available here.

In your local copy of the repo

Check the list of contributors

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 2.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
  • E. M. Bray
  • 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.

Check the change log

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" 2.2.0..HEAD

For a new major or minor version

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 main 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 main to the development version of whatever the new next major or minor version will be.

On the local main branch:

  • Edit the release date in CHANGES.rst and...
  • ...commit this change to git.
  • Tag commit with version number (e.g. 2.1.0): git tag 2.1.0
    • Version numbers in tags should not contain a leading v.
  • If multiple release branches will be maintained, make a new branch named, e.g. 2.1.x, on the commit tagged with the version number (e.g. 2.1.0)

For a patch release

This is only different from a major/minor release if patch releases are done from a separate branch; in ccdproc that is really not necessary because we do not do an LTS release.

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 to 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-pick the merge commits from master and apply them to the development branch. The only wrinkle has to do with telling git which 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 branch

Done with cherry-picking? Next steps are:

  • Push this updated branch to your github account and see if the tests pass.
  • Edit the release date in CHANGES.rst and add a new section for the next patch release.
  • Commit this change.
  • Tag that commit with the release number

Update the Author List on ASCL

Check the author list for the ccdproc entry on ASCL and edit if appropriate.

Testing/pushing to github

Push the change to your github account:

  • Push here first so that CI 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!
  • If the only change really is setting the release date you could maybe skip this step.

After tests pass push changes to the astropy github account:

  • To push the code changes on main: git push -v https://github.com/astropy/ccdproc.git main:main
  • To push the new tag to main (please push only the tag for this release): git push -v https://github.com/astropy/ccdproc.git 2.1.0
  • If you made a new branch, push that branch (the 2.1.x branch in this example): git push -v https://github.com/astropy/ccdproc.git 2.1.x:2.1.x

publishing on pypi

Prior to doing this, check that the tar file will build appropriately and contains everything that you do want. So run:

  • python -m build

And then check the resultant tarfile. If this fails you may need to install build.

Assuming you have already registered the project on pypi, doing a release is really easy:

  • twine upload dist/*

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

Update the conda package

Open a pull request at the conda-forge ccdproc feedstock, updating the version and checksum, or wait for the auto-tick bot to open the PR.

Generating docs for the new release on ReadTheDocs

This should no longer take a separate step. Just in case it is not showing up: 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.

Get ready for the next release

  • Add a new changelog section for the next release.
  • Commit this change.
Add a custom footer
Add a custom sidebar
Clone this wiki locally