Openff-toolkit: Standard release process

[j-wags]

1: Get PI approval from John Chodera or Jeff Wagner to release master "as is"

2: Update the release history, using this template

Tag = X.Y.Z @ master

Title = X.Y.Z [Descriptive Title]

# 0.8.0 Virtual Sites and Bond Interpolation

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

This release adds our largest feature yet, SMARTS-based creation of VirtualSites (also known as off-center charges), as well as functionality to handle bond parameter interpolation based on partial bond orders. 

For help getting the OpenFF Toolkit running, see our [installation instructions](https://open-forcefield-toolkit.readthedocs.io/en/latest/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!

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

4: Trigger a new build on Omnia.

This step is in flux. For now just build locally. With a few more hours of work we could get the automated package creation Action production-capable.

. build_local.sh 

Upload directly to main label:

anaconda upload -u omnia /Users/jeffreywagner/miniconda3/envs/build/conda-bld/noarch/openforcefield-0.8.0-pyh39e3cac_0.tar.bz2

Test the package

• Run the conda testing workflow

• In case of problems, use admin tools at:
  
  
  
  • https://anaconda.org/omnia/openforcefield/files
  
  
  • (Label is in the right column. If you have admin access, you should be able to check the packages you want to change)
  
  
  • Basically, if anything goes wrong, move the new package off the main label
  
  

4.5: Update the openforcefield README "Latest Release" badge

• Just commit directly to master

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

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

0.9.0 - Current development
---------------------------

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
• Set new release version as default version (here) display and SAVE

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!