Add automation of package release

Author: Mark R. Tuttle

.github/workflows/create_tagged_release.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+
+"""Create a GitHub release for a tagged commit."""
+
+import logging
+import os
+import re
+
+import github_release
+
+################################################################
+
+def extend_argument_parser(parser):
+    """Add flags to the command line parser."""
+
+    parser.add_argument(
+        '--source-package',
+        help='Path to pip source installation package.'
+    )
+
+    parser.add_argument(
+        '--binary-package',
+        required=True,
+        help='Path to pip binary installation package.'
+    )
+
+    parser.add_argument(
+        '--tag',
+        required=True,
+        help='GitHub tag of the package being released'
+    )
+
+    parser.add_argument(
+        '--version',
+        required=True,
+        help='Version of the package being released'
+    )
+
+    return parser
+
+def main():
+    """Create a GitHub release for a tagged commit."""
+
+    parser = github_release.argument_parser()
+    parser = extend_argument_parser(parser)
+    args = parser.parse_args()
+    args = github_release.argument_defaults(args)
+
+    if not os.path.isfile(args.binary_package):
+        raise UserWarning("Binary package does not exist: {}"
+                          .format(args.binary_package))
+
+    if not re.match(r'[\w.-]+', args.tag, re.ASCII):
+        raise UserWarning("Package version contains an illegal character: {}"
+                          .format(args.tag))
+
+    token = os.environ.get('GITHUB_TOKEN')
+    if not token:
+        logging.info(
+            'Failed to find GitHub token in environment variable '
+            'GITHUB_TOKEN'
+        )
+
+    repo_name = os.environ.get('GITHUB_REPOSITORY')
+    if not repo_name:
+        logging.info(
+            'Failed to find GitHub repository in environment variable '
+            'GITHUB_REPOSITORY'
+        )
+
+    repo = github_release.get_repository(repo_name, token)
+    assets = [
+        {
+            'path': args.binary_package,
+            'name': os.path.basename(args.binary_package),
+            'label': 'PIP installation package',
+            'type': 'application/binary'
+        }
+    ]
+    github_release.tagged_software_release(repo, args.tag, args.version,
+                                           assets)
+
+if __name__ == "__main__":
+    main()

.github/workflows/github_release.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+
+"""Manage GitHub software releases."""
+
+
+import argparse
+import logging
+import os
+
+import github
+
+NIGHTLY_TAG = 'nightly'
+NIGHTLY_BRANCH = 'master'
+
+TAGGED_RELEASE_MESSAGE = "tagged_release_message.md"
+
+################################################################
+
+def argument_parser():
+    """Parser for command-line arguments."""
+
+    parser = argparse.ArgumentParser(
+        description='Create GitHub software release with build artifacts.'
+    )
+    parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Verbose output.'
+    )
+    parser.add_argument(
+        '--debug',
+        action='store_true',
+        help='Debugging output.'
+    )
+
+    return parser
+
+def argument_defaults(args):
+    """Default values for command-line arguments."""
+
+    # Configure logging to print INFO messages by default
+    args.verbose = True
+    if args.debug:
+        logging.basicConfig(level=logging.DEBUG,
+                            format='%(levelname)s: %(message)s')
+    elif args.verbose:
+        logging.basicConfig(level=logging.INFO,
+                            format='%(levelname)s: %(message)s')
+    else:
+        logging.basicConfig(format='%(levelname)s: %(message)s')
+
+    return args
+
+################################################################
+
+def get_repository(full_name, token):
+    """GitHub repository with given name authenticated with given token."""
+
+    return github.Github(token).get_repo(full_name)
+
+def lookup_tag(repo, tag_name):
+    """The reference corresponding to a tag name."""
+
+    try:
+        ref = repo.get_git_ref('tags/{}'.format(tag_name))
+    except github.UnknownObjectException as error:
+        logging.info('Failed to find reference for tag %s: %s', tag_name, error)
+        return None
+
+    logging.info('Found reference for tag %s: %s', tag_name, ref)
+    return ref
+
+def lookup_release(repo, tag_name):
+    """The release corresponding to a tag name."""
+
+    for release in repo.get_releases():
+        if release.tag_name == tag_name:
+            logging.info('Found release for tag %s: %s', tag_name, release)
+            return release
+    logging.info('Failed to find release for tag %s', tag_name)
+    return None
+
+################################################################
+# Create a GitHub release for a versioned software release (a tagged
+# commit) with a set of installation packages for this version.
+
+def tagged_release_message(version, path=None):
+    """The message to use with a tagged release."""
+
+    path = path or TAGGED_RELEASE_MESSAGE
+    path = os.path.join(os.path.dirname(__file__), path)
+
+    try:
+        with open(path) as msg:
+            return msg.read().format(version)
+    except FileNotFoundError:
+        logging.info("Couldn't open tagged release message file: %s", path)
+        return "This is release {}".format(version)
+
+def create_tagged_release(repo, tag_name, version=None):
+    """Create a release for a tagged commit."""
+
+    release = lookup_release(repo, tag_name)
+    if release:
+        release.delete_release()
+        logging.info('Deleted release for tag %s: %s', tag_name, release)
+
+    reference = lookup_tag(repo, tag_name)
+    if not reference:
+        raise UserWarning("Tag does not exist: {}".format(tag_name))
+
+    version = version or tag_name.split('-')[-1]
+    release_name = tag_name
+    release_msg = tagged_release_message(version)
+    release = repo.create_git_release(tag_name, release_name, release_msg)
+    logging.info('Created release for tag %s: %s', tag_name, release)
+    if not release:
+        raise UserWarning("Failed to create tagged release for tag {}"
+                          .format(tag_name))
+
+    return release
+
+def upload_release_asset(release, path,
+                         label=None, content_type=None, name=None):
+    """Upload an asset (an installation package) to a release."""
+
+    filename = os.path.basename(path)
+    label = label or filename
+    name = name or filename
+    content_type = content_type or 'text/plain'
+
+    try:
+        asset = release.upload_asset(path, label, content_type, name)
+    except github.GithubException as error:
+        logging.info("Failed to upload asset '%s': %s", path, error)
+
+    logging.info("Uploaded asset '%s': %s", path, asset)
+    return asset
+
+def tagged_software_release(repo, tag_name, version=None, assets=None):
+    """Create a release for a tagged commit with a list of assets."""
+
+    # asset: {
+    #   path  : required string: local path to the assest to upload to GitHub
+    #   name  : string: filename to use for the asset on GitHub
+    #   label : string: text to display in the link to the asset in release
+    #   type  : string content type of the asset
+    # }
+    assets = assets or []
+
+    release = create_tagged_release(repo, tag_name, version)
+    for asset in assets:
+        upload_release_asset(release, asset['path'],
+                             label=asset.get('label'),
+                             content_type=asset.get('type'),
+                             name=asset.get('name'))
+
+################################################################
+# Create a GitHub release for a nightly build of a development branch
+# with a set of installation packages for the nightly build.
+#
+# This works by creating (updating) a 'nightly' tag for the tip of the
+# development branch, then creating an ordinary tagged release for
+# this newly tagged commit, but a) the release message tailored to a
+# nightly release, and b) the release type is set to "prerelease".
+#
+# One issue with this implementation is that the constant updating of
+# the 'nightly' tag will require constant forced pulls to the local
+# copy of the 'nightly' tag.  This annoyance is the primary reason
+# this implementation is not currently used.
+
+def update_nightly_tag(repo):
+    """Update the nightly tag to the tip of the development branch."""
+
+    reference = lookup_tag(repo, NIGHTLY_TAG)
+    if reference:
+        reference.delete()
+        logging.info('Deleted tag %s: %s', NIGHTLY_TAG, reference)
+
+    ref = 'refs/tags/{}'.format(NIGHTLY_TAG)
+    sha = repo.get_branch(NIGHTLY_BRANCH).commit.sha
+    reference = repo.create_git_ref(ref, sha)
+    logging.info('Created tag %s for branch %s (ref %s, sha %s): %s',
+                 NIGHTLY_TAG, NIGHTLY_BRANCH, ref, sha, reference)
+
+def create_nightly_release(repo):
+    """Create a tagged release for the nightly commit."""
+
+    release = lookup_release(repo, NIGHTLY_TAG)
+    if release:
+        release.delete_release()
+        logging.info('Deleted release for tag %s: %s', NIGHTLY_TAG, release)
+
+    update_nightly_tag(repo)
+    reference = lookup_tag(repo, NIGHTLY_TAG)
+    if not reference:
+        raise UserWarning("Tag does not exist: {}".format(NIGHTLY_TAG))
+
+    release_name = "Nightly release"
+    release_msg = "This is a nightly release"
+    # GitHub doesn't display release with draft=False, prelease=True
+    release = repo.create_git_release(NIGHTLY_TAG,
+                                      release_name, release_msg,
+                                      prerelease=True)
+    logging.info('Created nightly release with tag %s for branch %s: %s',
+                 NIGHTLY_TAG, NIGHTLY_BRANCH, release)
+    if not release:
+        raise UserWarning(
+            "Failed to create nightly release with tag {} for branch {}"
+            .format(NIGHTLY_TAG, NIGHTLY_BRANCH))
+    return release
+
+def nightly_software_release(repo, assets=None):
+    """Create a tagged release for the nightly commit and pacakges."""
+
+    # asset: {
+    #   path  : required string: local path to the assest to upload to GitHub
+    #   name  : string: filename to use for the asset on GitHub
+    #   label : string: text to display in the link to the asset in release
+    #   type  : string: content type of the asset
+    # }
+    assets = assets or []
+
+    release = create_nightly_release(repo)
+    for asset in assets:
+        upload_release_asset(release, asset['path'],
+                             label=asset.get('label'),
+                             content_type=asset.get('type'),
+                             name=asset.get('name'))
+
+################################################################

.github/workflows/release.yaml

@@ -0,0 +1,56 @@
+name: CBMC viewer release
+
+# A new release is triggered by a new tag of the form viewer-VERSION
+on:
+  push:
+    tags:
+      - viewer-*
+
+jobs:
+  Release:
+    name: CBMC viewer release
+    runs-on: ubuntu-18.04
+
+    steps:
+
+      - name: Checkout the repository
+        uses: actions/checkout@v2
+
+      - name: Set the package version
+        run: |
+          # The environment variable GITHUB_REF is refs/tags/viewer-*
+          echo "::set-env name=TAG::${GITHUB_REF:10}"
+          echo "::set-env name=VERSION::${GITHUB_REF:17}"
+          printenv | sort
+          cat ${GITHUB_EVENT_PATH}
+
+      - name: Create the package
+        run: |
+          # Patch the version number the source to be consistent with the tag
+          sed -i.bak \
+            "s/NUMBER *=.*/NUMBER = \"${VERSION}\"/" \
+            cbmc_viewer/version.py
+
+          # Patch the version number pip setup to be consistent with the tag
+          sed -i.bak \
+            "s/version *=.*/version = \"${VERSION}\",/" \
+            setup.py
+
+          # Create the package
+          python3 -m pip install --upgrade setuptools wheel
+          make pip
+
+          # Record the package name
+          # The source *.zip and binary *.whl packages are in dist
+          echo "::set-env name=PACKAGE::$(ls dist/*.whl)"
+
+      - name: Create the release
+        env:
+          # GitHub creates this secret for authentication in a workflow
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python3 -m pip install --upgrade pygithub
+          python3 .github/workflows/create_tagged_release.py --verbose \
+            --binary-package ${PACKAGE} \
+            --tag ${TAG} \
+            --version ${VERSION}

.github/workflows/tagged_release_message.md

@@ -0,0 +1,14 @@
+This is the CBMC Viewer version {}.
+
+To install this release, download the "PIP installation package" as $PACKAGE and run
+```
+  sudo python3 -m pip install --upgrade $PACKAGE
+```
+
+
+To get the best results, install Exuberant Ctags with the following commands:
+```
+  On MacOS:   brew install ctags
+  On Ubuntu:  sudo apt-get install ctags
+  On Windows: Download from https://sourceforge.net/projects/ctags
+```