Standard release process

[j-wags]

1: Get approval from Jeff Wagner (or current product owner) to release main "as is"

2: Create a new release on GitHub, following this template:

https://github.com/openforcefield/openff-toolkit/releases/new

Tag = X.Y.Z @ master

Title = X.Y.Z [Descriptive Title]

# 0.10.1 Minor feature and bugfix release

[**For the complete release notes, please see our documentation**](https://open-forcefield-toolkit.readthedocs.io/en/stable/releasehistory.html)

For help getting the OpenFF Toolkit running, see our [installation instructions](https://open-forcefield-toolkit.readthedocs.io/en/stable/installation.html).

Please report bugs, request features, or ask questions through our [issue tracker](https://github.com/openforcefield/openff-toolkit/issues).

**Please note that there may still be some changes to the API prior to a stable 1.0.0 release.**

Add the "See our install instructions" block verbatim from above

Check This is a pre-release, and click Release!

2.5: Update the stable tag to point to the newest release/latest commit

Just run this action

3: Trigger a new build on conda-forge.

Get a fork of the feedstock repo

If you don't have a personal fork of https://github.com/conda-forge/openff-toolkit-feedstock, then make one.

If you do have an old personal fork of https://github.com/conda-forge/openff-toolkit-feedstock, then update it with the most recent changes by running (replacing j-wags with your GH username)

git pull --set-upstream [email protected]:conda-forge/openff-toolkit-feedstock.git
git push --set-upstream [email protected]:j-wags/openff-toolkit-feedstock.git

Update the build info

in recipe/meta.yaml, update

• The version string at the top
• The build number to 0 if that's not already set
• Update the SHA with the value from the latest release. Get this using curl -sL https://github.com/openforcefield/openff-toolkit/archive/X.Y.Z.tar.gz | openssl sha256
• Add any new dependencies since the last release (Looking at recent changes to the test env may help catch these)

Open a PR from your fork to conda-forge/openff-toolkit-feedstock

Follow instructions, including rerendeing and such. Once tests pass, go ahead and merge.

Test the package

• Run the conda testing workflow

4: Update repo text

Edit the release page to add the Zenodo badge by copying the version-specific badge from here.

Update the openforcefield README "Latest Release" badge. Also ensure the "How to cite" section is up to date. Just commit directly to master

Make a new, empty Current Development header in releasehistory.rst

Add something like the following to the top of releasehistory.rst

## Current development

### API-breaking changes

### Behavior changes

### Bugfixes

### New features

### Improved documentation and warnings

Per @SimonBoothroyd:

This way the first PR after a release isn't responsible for creating the new section and keeps things a bit more single purpose and less likely to create merge conflicts on the file.

5: Build the single-file installers

• Trigger the Make single-file installers workflow
• Once complete, download the four artifacts from the builds
• Rename the downloaded artifacts according to this pattern:

mv ubuntu-latest_py3.7.sh.zip openforcefield-0.8.0-py37-Linux-x86_64.sh.zip
mv ubuntu-latest_py3.6.sh.zip openforcefield-0.8.0-py36-Linux-x86_64.sh.zip
mv macOS-latest_py3.6.sh.zip openforcefield-0.8.0-py36-MacOSX-x86_64.sh.zip
mv macOS-latest_py3.7.sh.zip openforcefield-0.8.0-py37-MacOSX-x86_64.sh.zip

• Unzip all the installers
• Edit the release to include all 4 installers as assets

6: Update the ReadTheDocs build versions

• Trigger RTD build of latest (we need to do this to make RTD aware of the new tagged release)
  • Go here, specifically to the bottom under "Actviate a version." A build named after the new version should be listed, click "Activate." On the next page, check the "Active" box but not the "Hidden" box. and click SAVE.
  • The build should be running in this.
• Verify new version docs have built and pushed correctly
• Manually build the docs for the stable tag (since RTD doesn't care that we updated it on GitHub, we need to tell it explicitly to rebuild)

7: Announce the release

Post something like this in #general

@channel We're pleased to announce the release of the Open Force Field Toolkit version 0.9.1! This is a minor release with small new features and small bugfixes. Detailed release notes are available at https://open-forcefield-toolkit.readthedocs.io/en/0.9.1/releasehistory.html

Conda packages available now on the `conda-forge` channel!
https://anaconda.org/conda-forge/openff-toolkit/files

Single-file installers are available in the "assets" section of the GitHub release, at https://github.com/openforcefield/openff-toolkit/releases/ 

8: Tweet the release

• Tweet something like

We're pleased to announce the release of the Open Force Field Toolkit version 0.5! This release introduces support for GBSA, along with several bugfixes and other improvements. Detailed release notes are available at https://open-forcefield-toolkit.readthedocs.io/en/0.5.0/releasehistory.html

• UNPIN the previous release announcement
• PIN the new release announcement

9. Draft highlights for email

• Should be a few bullet points of the most important features of the release.
  • Possibly only for minor releases, not patches?
• See Communication & Outreach / News on Confluence

[jchodera]

It would be great to make this a Markdown checklist in openforcefield/devtools/

Also, the PI approval can likely be replaced by a sufficiently mature checklist. Perhaps we can skip that step with the idea that, once we've established the process, PI sign-offs is no longer needed? PI input should come at the level of helping shape release plans earlier through communicating which issues are critical or urgent.

[j-wags]

That sounds good. I'm keeping this as an Issue for now, since it'll be easier to edit while we work out the process. But yes, we should transfer this into devtools once it's worked out.

And I'm planning on removing point 1) once we have a few more of these under our belt.

[jchodera]

Some potential additions:

The RTD docs didn't auto-update when 0.3.0 was cut. We should add some steps to the build checklist to ensure this happens:

• Trigger RTD build of latest
• Add new release version to list of built versions and SAVE
• Verify new version docs have built and pushed correctly
• Set new release version as default version to display and SAVE

[jchodera]

Also, should we have a policy of back-porting the more detailed release notes on GitHub back into the sphinx docs release history?
Compare: https://open-forcefield-toolkit.readthedocs.io/en/0.3.0/releasehistory.html
with: https://github.com/openforcefield/openforcefield/releases/tag/0.3.0

[j-wags]

Per discussion on Slack, we should include the full-text names of functions whose behavior is changing, as well as functions being added or removed. This will be especially useful as we make a larger number of releases and users need to Ctrl-F to find a specific keyword.

[j-wags]

Also, should we have a policy of back-porting the more detailed release notes on GitHub back into the sphinx docs release history?

@jchodera

I don't want to introduce more back-porting than is absolutely necessary, so maybe we could draft the summary text in releasenotes.rst above the bullet points? We could even do this in a "release cutting" PR to get these notes formally reviewed+approved. That would also give us a single clean PR to clean up any other irregularities.

[jaimergp]

I have a couple of suggestions, in increasing complexity:

• Keep the current strategy, but include a link to the corresponding GH release (maybe using a badge?).
• Make Sphinx/RTD the main source for release notes. Changes get approved in a PR. Once everything is ready, that text is copied/linked in the GitHub release entry

Some more thoughts are available here Keep A Change Log.

[j-wags]

@jaimergp Now that I've done this a few times, I definitely agree with the second point.

The first seems circular, but maybe I'm not understanding it correctly (The RTD can't have a link to the release page, since the RTD is a snapshot of what the docs were at the time of release, so by defnition the release hasn't happened yet when the RTD content is set)

[SimonBoothroyd]

@j-wags maybe append to this: Create a new placeholder section in the release history file for the next release. This way the first PR after a release isn't responsible for creating the new section and keeps things a bit more single purpose and less likely to create merge conflicts on the file!

[j-wags]

Great call. Added as step 4.75!

[Yoshanuikabundi]

@j-wags Yesterday we discussed adding a step to tap Binder so that the latest release would always be cached and ready to go. I checked around and this won't work; Binder doesn't have a facility to point to the latest release, only to a branch. So as soon as a pull request is merged after a release, the cache would be invalidated again.

My suggestion to get around this would be to create a new branch, latest or stable, that always tracks the latest release. This way instead of linking to the Binder for the master branch, we can link to the Binder for the latest branch, and the cache can last until the next release, which should speed up using Binder examples for end users. Then we can add the discussed step here and it will actually have a purpose. The branch might be useful or other stuff too.

If you agree with that approach, should we automate updating the branch? It should be very easy to write a GH action that automatically updates the branch when a release is published, or at any other stage during the drafting of a release.

An alternative might be to just link to the latest release tag directly, but that means at every release you'd have to update all the Binder links in the codebase.

[jaimergp]

I think you can also use a moving tag instead of a branch. Or use the GitHub API to return the latest release tag.

[j-wags]

Yesterday we discussed adding a step to tap Docker so that the latest release would always be cached and ready to go.

Quick clarification -- I think we had talked about this with respect to Binder, not Docker. Binder is using Docker behind the scenes, but currently that's out of our hands -- All we tell Binder is "do something with environment.yml". This file is interpreted entirely as a conda input, which doesn't provide us with a way to specify anything at the Docker level.

So, I assume you're talking about switching Binder to use a Docker image instead of that yaml file, which is a good idea. IIRC, public images are generally hosted on DockerHub. I can't recall whether we have an openforcefield dockerhub -- I had worked with @dotsdl on a start to this, but I can't recall the conclusion.

We could make this image creation be a GitHub action that's automatically triggered by a release. This would also have us start publishing a dockerfile, which would close #416.

[Yoshanuikabundi]

Oops. I meant Binder. cat last_comment | sed s/Docker/Binder/g. I will edit my previous comment for clarity. Sorry!

I was literally just talking about adding a new branch and changing the links to *Binder. So, from

https://mybinder.org/v2/gh/openforcefield/openforcefield/master?filepath=%2Fexamples%2F

To

https://mybinder.org/v2/gh/openforcefield/openforcefield/latest?filepath=%2Fexamples%2F

Now that you mention it though, we could just adapt these instructions to do what you're saying on release. I'll open a PR after the weekend.

[mattwthompson]

use the GitHub API

Seems like a much cleaner (and easier to write) solution than my git/shell-foo

openff-toolkit/.github/workflows/conda.yml

Lines 99 to 127 in e01e47c

	- name: Check that correct OFFTK version was installed
	shell: bash -l {0}
	run: |
	# Go up one directory to ensure that we don't just load the OFFTK from the checked-out repo
	cd ../
	export LATEST_TAG=$(git ls-remote --tags https://github.com/openforcefield/openff-toolkit.git | cut -f2 | grep -v "rc" | tail -1 | sed 's/refs\/tags\///')
	export FOUND_VER=$(python -c "import openff.toolkit; print(openff.toolkit.__version__)")
	echo "Latest tag is"
	echo $LATEST_TAG
	echo "Found version is"
	echo $FOUND_VER
	if [[ $LATEST_TAG != $FOUND_VER ]];
	then echo "Version mismatch"
	exit 1
	fi
	cd openff-toolkit
	- name: Test the package
	shell: bash -l {0}
	run: |
	export LATEST_TAG=$(git ls-remote --tags https://github.com/openforcefield/openff-toolkit.git | cut -f2 | grep -v "rc" | tail -1 | sed 's/refs\/tags\///')
	# Checkout the state of the repo as of the last release
	git fetch --tags
	git checkout tags/$LATEST_TAG
	git log -1 | cat