Skip to content

Release Process

Jump to bottom
Jeff Wagner edited this page Apr 22, 2024 · 31 revisions

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.
  • Update the date in the FF files
  • Update the authors in the .zenodo.json file - Details and validation info can be found here
  • 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 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 = 2023.04.1 @ master

Title = Sage 2.1.0 Release Candidate 1 

The new force field files in this release are adapted from `fb-fit/result/optimize/force-field.offxml` in `release_2.1.0-rc.1.tar.gz` from the Assets of this release. 

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-. The parameters have been co-optimized to TIP3P water, therefore this contains parameters for TIP3P, including bond length constraints.

ALWAYS check "this is the latest release", and NEVER check "this is a pre-release" (even for RCs... I made this choice arbitrarily but we should prioritize consistency unless there's a clear reason to do otherwise)

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: Trigger build of the new release on conda-forge

git pull --set-upstream git@github.com:conda-forge/openff-forcefields-feedstock.git
git push --set-upstream git@github.com:j-wags/openff-forcefields-feedstock.git
  • If you DO NOT have an existing personal fork of the feedstock, create one of https://github.com/conda-forge/openff-forcefields-feedstock
  • In your fork, make 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)
  • Make the following changes to recipe/conda_build_config.yaml
    • Select the correct label according to CFEP-05
      • alpha or pre-alpha gets the openff_forcefields_dev label
      • rc or beta gets openff_forcefields_rc
      • anything more mature gets main
  • None of the above bullet makes any sense now that we're on calver - Folks will just need to be careful if they have automatic-latest-FF-finding logic.
  • 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: If this is a major release, update FFs in Open Force Field toolkit examples

7: If this is a major or minor release, update the website

8: If this is a major or minor release, 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 and linkedin if it's a major release
Clone this wiki locally