Release Process: Annotation File Utilities, Checker Framework

This document explains how to make a release of the Checker Framework and the Annotation File Utilities. The process takes around 2 hours (including manual steps) when all goes according to plan. However, the lengthiest steps are automatic so you will be able to work on other tasks.

Contents:

• Step by Step
• Continuous integration tests
• Deploy to local Maven repository
• Snapshot release
  • Using a snapshot release
    • Gradle Groovy (build.gradle file)
    • Gradle Kotlin (build.gradle.kts file)
    • Maven (pom.xml file)
• Pre-release Checklist
• Release Process Overview
  • File Layout
  • Release Scripts
• Changelog Guidelines
  • Content Guidelines
  • Style Guidelines
• Backing Out an Uncommitted Release
  • Manual Steps to Back Out a Release
• Future Improvements

Step by Step

More information about the steps is provided in the code comments of the main() functions of the release_build and release_push scripts. Please read those comments if you have never done so before.

Answering 'no' to a prompt does not exit the script unless otherwise indicated.

Be sure to carefully read all instructions on the command-line before answering 'yes' to a prompt. This is because the scripts do not ask you to say 'yes' after each step, so you may miss a step if you only read the paragraph asking you to say 'yes'.

1. If you have never made a release before, follow the instructions in the Pre-release Checklist.
2. Update stubparser. If there has been a JavaParser release since the last Checker Framework release, update Stubparser from JavaParser. Do this on your own computer; it doesn't have to be done on the CSE file system..
3. On your own computer, update the Checker Framework source code in the master branch:
   • Update the AWS Java SDK BOM dependency. In file checker/build.gradle, edit the com.amazonaws:aws-java-sdk-bom dependency to be the latest version number at https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk. (The next time Dependabot opens a pull request for that dependency, you might need to respond @dependabot ignore this dependency to prevent such pull requests for the next month.)
   • Update AFU and Checker Framework change logs by following the instructions at content guidelines.
   • Update the Checker Framework version number in checker-framework/build.gradle, in the allprojects block. (The AFU version is updated as part of the release scripts.)

     Update the minor version (middle number in the version number) if there are any incompatibilities with the previous version. This includes incompatibilities for people who are maintaining a checker, which happens if the signature changes for any method in these classes:

     AnnotatedTypeFactory
     BaseAnnotatedTypeFactory
     GenericAnnotatedTypeFactory
     CFTransfer
     CFAbstractTransfer
     CFAbstractAnalysis
     CFAnalysis
     CFAbstractStore
     CFStore
     CFAbstractValue
     CFValue
     BaseTypeVisitor
     BaseTypeChecker
     SourceChecker
     MultigraphQualifierHierarchy
     AbstractQualifierPolymorphism
     AnnotationUtils
     TreeAnnotator
     

     (TODO: Write a command that diffs these classes between the previous and current release.)

     A rule of thumb is that any framework change that requires changes to more than one type-checker should be at least a minor version (middle number in the version number) bump.

   • Update the Annotation Tools version number, again in the master branch, in annotation-file-utilities/build.gradle. (TODO: Are any other replacements necessary?)
   • Commit and push these changes to typetools/master.
4. Log into a machine on the CSE file system, such as tern.
   ssh $USER@tern.cs.washington.edu

5. In a user-specific temporary directory, clone/update the Checker Framework repository (it contains the release scripts).
   mkdir -p /scratch/$USER/cf-release
chown -R types_www /scratch/$USER/cf-release
chmod -R g+rw /scratch/$USER/cf-release
cd /scratch/$USER/cf-release
test -d checker-framework && (cd checker-framework && git pull --ff-only --quiet) || git clone --quiet https://github.com/typetools/checker-framework.git
cd checker-framework/docs/developer/release
(The release scripts will checkout and build all dependencies.)
6. Run release_build to create the release artifacts and place them in the development website
   git pull && python3 release_build.py all
   
   For verbose debugging output, use the --debug option.
   
   Note: The "all" argument specifies that all projects should be built. There has been some work done in order to select only specific projects (AFU and Checker Framework) to be built but more work still needs to be done. Just pass "all" for now.
7. Run release_push to run a few tests and move release artifacts from the development website to the live site and to Maven Central
   python3 release_push.py release
   
   
   Note: The "release" argument states that you intend to do an actual release. If you just want to test the script, leave out "release" and the script will run but not update anything.
   If you get an obscure error about permissions, try running the release_push script several times in a row. This will sometimes update the repository permissions such that the script can proceed further each time.
8. Update list of qualifiers in Project Lombok. Follow the instructions in HandlerUtil.java. If the release did not add, remove, or rename any type qualifiers, no changes are required. Those instructions do not work on macOS, so you may need to use a Linux machine to make the changes.
9. Update the Annotation Tools' use of the Checker Framework by making a pull request that changes two occurrences of the old version number in annotation-file-utilities/build.gradle.
10. Make Daikon use the latest Checker Framework version. Follow the instructions in java/lib/README to update the Checker Framework version number in Daikon.

Continuous integration tests

The following continuous integration tests should all pass before you make changes that you need to test. If not, notify the relevant team members. Refresh this page to see the latest status.

• Annotation File Utilities:
• Checker Framework:
• JDK:
• Daikon:

Deploy to local Maven repository

To deploy to a local Maven repository, run ./gradlew PublishToMavenLocal in checker-framework.

Then, update your project's buildfile. For Maven, just update the Checker Framework version number. For Gradle, also add repositories { mavenLocal() }.

Often, the version number in checker-framework/build.gradle (in allprojects { version ... }) will end in -SNAPSHOT, but this is not a requirement. Regardless of the version number, beware that you may get different results than on other computers that have not deployed the same commit of the Checker Framework to their local Maven repository.

Snapshot release

To release the Maven artifacts to the Maven Central snapshot repository:

1. Ensure that ~/.gradle/gradle.properties includes your SONATYPE_NEXUS_USERNAME and SONATYPE_NEXUS_PASSWORD.
2. Ensure that the version number in checker-framework/build.gradle (in allprojects { version ... }) ends in -SNAPSHOT.
3. Run ./gradlew publish in checker-framework.

Using a snapshot release

Gradle Groovy (build.gradle file)

repositories {
  ...
  maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
}

ext.checkerFrameworkVersion = '3.28.1-SNAPSHOT'
dependencies {
  compileOnly "org.checkerframework:checker-qual:${checkerFrameworkVersion}"
  testCompileOnly "org.checkerframework:checker-qual:${checkerFrameworkVersion}"
  checkerFramework "org.checkerframework:checker:${checkerFrameworkVersion}"
}
configurations.all {
  resolutionStrategy.cacheChangingModulesFor 0, 'seconds'
}

Gradle Kotlin (build.gradle.kts file)

val checkerFrameworkVersion = "3.41.1-SNAPSHOT"
dependencies {
   compileOnly("org.checkerframework:checker-qual:${checkerFrameworkVersion}")
   testCompileOnly("org.checkerframework:checker-qual:${checkerFrameworkVersion}")
   checkerFramework("org.checkerframework:checker:${checkerFrameworkVersion}")
}
configurations.all({
   resolutionStrategy.cacheChangingModulesFor(0, "seconds")
})

Maven (pom.xml file)

    <repository>
      <id>snapshots-repo</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
      <releases><enabled>false</enabled></releases>
      <snapshots><enabled>true</enabled></snapshots>
    </repository>

Pre-release Checklist

If you have not performed a release before you must follow these steps.

SONATYPE_NEXUS_USERNAME=your_user_name
SONATYPE_NEXUS_PASSWORD=your_password

git config --global user.name "Your Name"
git config --global user.email you@example.com

Release Process Overview

This section first explains the structure of the projects on disk on tern, then lists scripts used during the release process.

File Layout

Release Scripts

As mentioned above, in order to release the Checker Framework you must run two scripts, release_build.py and release_push.py but there are supporting scripts and files in the release directory. Some of these files are described below.

Changelog Guidelines

Each developer is responsible for updating project changelogs to reflect changes they have made each month. The changelogs should be updated by "feature freeze" though at the latest this should be done before "code freeze". Before releasing, the person performing the release will be asked to verify the changelogs. Please check that there aren't typos (i.e. missing release date/version information, spelling errors, etc...). Also check that the changelog obeys the guidelines below.

Content Guidelines

• Only (and all) changes that affect users (including type system developers) go into the changelog. If a change is breaking, no matter how small, mention it.
• Even if some code has been committed to the repository, don't announce the feature until it has been documented in the manual.
• Checker Framework:
  • List all issues (in issue trackers) resolved since the previous release: previous release, issues query, current changelog.
  • Ensure the changelogs reflect version control commits since the last release, via the command line:
    cd $CHECKERFRAMEWORK && git log --name-status `git describe --abbrev=0 --tags`..
    or via GitHub Checker Framework commit logs.
  • Ensure the changelogs reflect changes to the manual since the last release, via the command line:
    cd $CHECKERFRAMEWORK && git diff -w `git describe --abbrev=0 --tags` docs/manual
• Annotation File Utilities:
  • List all issues (in issue trackers) resolved since the previous release: previous release, issues query, current changelog
  • Ensure the changelogs reflect version control commits since the last release, via the command line:
    cd $CHECKERFRAMEWORK/../annotation-tools && git log --name-status `git describe --abbrev=0 --tags`..
    or via GitHub Annotation File Utilities commit logs.
  • Ensure the changelogs reflect changes to the manual since the last release, via the command line:
    cd $CHECKERFRAMEWORK/../annotation-tools && git diff -w `git describe --abbrev=0 --tags` annotation-file-utilities/annotation-file-utilities.html

Style Guidelines

• Changes are written from the user's perspective. Don't include implementation details that users don't care about.
• To be consistent, write in the past tense (e.g. "Added option for verbose error messages").
• Lines should not exceed 80 characters wide.
• Break the different programs into their own sections. See notes on release 1.7.0 and 1.5.0 for an example. Tools should have their own section within the Checker Framework release notes (excluding issue fixes from the issue tracker).
• Be specific. Don't write something like "added a few options to Eclipse plugin". Do write "added options to the Eclipse plugin to include stub files, ignore warnings, and show verbose output."

Backing Out an Uncommitted Release

At the time of this writing, there are 2 steps that cannot be reverted.

1. The push from the interm repositories to the GitHub (release) repositories
2. The release of the staged Maven artifacts

If you have executed either of these steps and then realized there is a breaking error, you should do another release. The release script will allow you to do a point release like "1.8.0.1" when a version "1.8.0" already exists.

If you have NOT committed an irreversible step then you can follow the steps below to point the live release to a previous release. You can then redo the original release. Make sure to say "yes" when the release script asks you to delete the old directories.

Manual Steps to Back Out a Release

• Drop the artifacts from Central
  You may have staged and then closed the artifacts in the Sonatype Central repository. Drop (do NOT release) these artifacts. See the Sonatype OSS Repository Usage Guidelines.

Note: You may find yourself copying release directories for some reason or other. It is important to remember that the symlinks may be absolute. You should check any symlinks that may be affected by the move and ensure they point to the new location and not the old one.

Future Improvements

Below is a roughly priority-ordered list of future improvements. In a perfect world we would do all of these. At the moment, I believe only the first 2 (Open JDK Javadoc Fixes, and More Sanity Checks) should have any appreciable priority.

More Sanity Checks

Tasks:

• Implement one of the sanity checks mentioned in this section.
• Add your sanity check to the appropriate location in the release_push script.
• Update this document to reflect the new steps.

Sanity Checks:

• Run tutorial sanity check automatically via command line.

Release in Continuous Integration

Tasks:

• Create a tern task to run the release_build script without prompting.
• Observe the output of this task and identify possible errors.
• Fix up all observed errors until the release_build script runs without error.
• We probably want to move the link checking of the development site to the release_build script and write it out to disk. This will allow the developer releasing the framework to consult pre-made link-checking results rather than waiting for the link checker to execute in the push script.

Auto-copy Release Scripts

Tasks:

• Create a read-only script in cf-release/scripts.
• Edit the script so that it downloads all release scripts into the cf-release directory.
• Update this document to reflect this new process.

Option Parsing

Tasks:

• Look up the latest Python parsing library.
• Replace the option parsing in the release_build.py and release_push.py scripts with library calls.

Optional Projects

Tasks:

• Improve option parsing to allow the user to select only certain projects to build.
• Improve scripts to resolve dependencies between projects and only build the selected projects and their dependencies.

REPL Mode

Tasks:

• Further separate the steps of the release process.
• Provide a default parameterization for these steps to make them easily runnable from the command line.
• Provide a script to launch Python with these commands on its path.
• Update this README to document the new functionality.