Release Process

Based on https://github.com/openforcefield/openforcefield/issues/286

This is something like a pre-flight checklist to make sure we don't make unnecessary errors in the process of releasing new FFs.

1: Prepare changes in a PR

• Open a new branch or fork on this repo.
• Add the new force field file to the branch.
• Check that regular and unconstrained forcefields have constraints applied and absent, respectively
• Ensure that there are no cosmetic attributes
• Visually inspect for whitespace irregularities, etc. (Importantly: Tabs should be turned into 4 spaces)
• Ensure that comments, dates, and authors are up to date
• Ensure that Bonds version="0.4", fractional_bondorder_method="AM1-Wiberg" and fractional_bondorder_interpolation="linear"
• Ensure that ProperTorsions version="0.4", fractional_bondorder_method="AM1-Wiberg" and fractional_bondorder_interpolation="linear"
• Ensure the Electrostatics scale14 value is 0.8333333333 (10 sig figs). Change it by hand if more 3's need to be added.
• Add monoatomic ion charges to the FF, just before the ToolkitAM1BCC tag:

    <LibraryCharges version="0.3">
        <LibraryCharge name="Li+" smirks="[#3+1:1]" charge1="1.0*elementary_charge"/>
        <LibraryCharge name="Na+" smirks="[#11+1:1]" charge1="1.0*elementary_charge"/>
        <LibraryCharge name="K+" smirks="[#19+1:1]" charge1="1.0*elementary_charge"/>
        <LibraryCharge name="Rb+" smirks="[#37+1:1]" charge1="1.0*elementary_charge"/>
        <LibraryCharge name="Cs+" smirks="[#55+1:1]" charge1="1.0*elementary_charge"/>
        <LibraryCharge name="F-" smirks="[#9X0-1:1]" charge1="-1.0*elementary_charge"/>
        <LibraryCharge name="Cl-" smirks="[#17X0-1:1]" charge1="-1.0*elementary_charge"/>
        <LibraryCharge name="Br-" smirks="[#35X0-1:1]" charge1="-1.0*elementary_charge"/>
        <LibraryCharge name="I-" smirks="[#53X0-1:1]" charge1="-1.0*elementary_charge"/>
    </LibraryCharges>

• Ensure that new FFs are loadable in newest stable release of OFF toolkit
• Draft a "version" description at the bottom of the README file in a branch or fork. A zenodo DOI link is not necessary at this stage
• Prepare the fitting tarball (or other record of the files and/or code that produced the new parameters), which is often associated with a release like this. This collection of assets should include:
  • a static copy of the data (QM and phys prop) used for the fit
  • a static copy of the scripts used for the fit
  • A file containing the environment used for the fit (like the output of conda env export)
  • Generally, anything else required to re-run the exact fit that was performed
• Open a PR to master, for example this

2: Get PR approved by at least one repo maintainer and check GitHub Actions runs

There are two sets of GitHub Actions scripts that should run automatically on the PR. Both must pass (✅ ) to merge the PR.

• CI: These tests basic behavior of the openforcefields package, i.e. that the OFFXML files can be loaded as expected. These do not include rigorous testing of the accuracy of the force field.
  • If the checks named `CI: / Test on ...# have a green check mark, there is no need to look further.
• Canary tests: These test some very basic physics, ensuring only that some simulations do not immediately crash, but no rigorous or broad tests for correctness. These tests should run automatically if new *.offxml files are found in the feature branch and should only take a few minutes. To verify these tests run and pass,
  • Click "Details" on any canary status check and look for sections named "Run x canary tests"
  • Ensure that some tests are run by looking for print statements like Running HMR with force field openff-x.y.z and molecule with SMILES <SMILES> and verifying that there are no errors.
  • Manually inspect these logs even if the status checks report a passing status. Do this for the log file of at least one run on each operating system (Linux and macOS).

Any test failures in either above checks are blocking. This include status checks reported as failures (:x:) or canary tests being skipped (possibly reporting an erroneous ✅ )

Reviewer: Confirm that all criteria in step 1 are met and that steps have been done correctly. This may take upwards of an hour.

3: Cut an official release, following this template:

Tag = X.Y.Z @ master

Title = Version 1.3.0 "Parsley" Update

The new force field files in this release are adapted from `result.offxml` in `release_1.3.0.tar.gz` from the Assets of [`Version 1.3.0 "Parsley"`](https://github.com/openforcefield/openforcefield-forcebalance/releases/tag/v1.3.0). See that release page for more details.

This force field is applicable to druglike molecules consisting of the elements C, H, O, N, P, S, F, Cl, Br, and I, and the monoatomic ions Li+, Na+, K+, Rb+, F-, Cl-, Br-, and I-. 

4: Edit the README page to add the most recent Zenodo badge by copying the version-specific badge from here:

• The badge needs to be added to the appropriate row(s) in the "filename -> DOI" table in the README

5: Copy the latest version of the version/DOI table to https://github.com/openmm/openmmforcefields/issues/115, overwriting the original post

This is no longer necessary since openmmforcefields can inspect to see all available force fields.

6: Trigger build of the new release on conda-forge

• Create a fork of https://github.com/conda-forge/openff-forcefields-feedstock with the following changes to recipe/meta.yaml:
  • version set to match git release
  • hash set to the output of curl -sL https://github.com/openforcefield/openff-forcefields/archive/X.Y.Z.tar.gz | openssl sha256 (fill in the version)
  • IF THE NEW VERSION HAS A - CHARACTER IN THE TAG, then the conda-forge version field needs to EXCLUDE that - character, and it should use a string-replace to add it (for example here)
• Open PR to merge your fork into conda-forge/openff-forcefields-feedstock:master
  • PR name should have new version string in it, eg Update for 1.3.1 release
  • Follow all checkbox instructions in conda forge's PR template, deleting those which don't apply.
  • No PR body text other than the default checklist are needed.
• Get a maintainer to review+approve, then merge!

6.5 (Only if needed/requested) Make legacy openforcefields package

• Clone https://github.com/omnia-md/conda-recipes
• in offline-builds/openforcefields/meta.yaml, edit the versions to reflect the recent release
• Make/activate an environment with the conda-build and anaconda packages installed
• Run . build_local.sh
• Watch the output for the file path of the final conda package, then run (for example) anaconda upload -u omnia /Users/jeffreywagner/miniconda3/envs/off-tk-dev/conda-bld/noarch/openforcefields-2.0.0rc.2-py_0.tar.bz2

7: If this is a major release, update FFs in Open Force Field toolkit examples

8: If this is a major release, rebuild most recent OFFTK single-file installer with new version of openforcefields

9: Update the website

• Update the website.

10: Announce the release!

• Announce in the Open Force Field Slack's #general channel (Do a @channel blast if it's a major release)
• Announce on twitter if it's a major release
• Announce on Open Force Field mailchimp list (@davidlmobley can provide access)