Merge pull request #5517 from NlightNFotis/ada-637-release-page-instr…

…uctions

Update Release Process script and add Installation Instructions to the Release Page

.github/workflows/regular-release.yaml

@@ -1,66 +1,83 @@
 on:
-  schedule:
-#            ┌───────────── minute (0 - 59)
-#            │ ┌───────────── hour (0 - 23)
-#            │ │ ┌───────────── day of the month (1 - 31)
-#            │ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
-#            │ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
-#            │ │ │ │ │
-#            │ │ │ │ │
-#            │ │ │ │ │
-    - cron: '0 9 * * THU'
-      # ^ this means 9:00 AM every thursday
-      # I can’t figure out the right syntax
-      # for ‘every other thursday’
+  push:
+    tags:
+      - 'cbmc-*'
+
+name: Create Release
 
 jobs:
-  bump_cbmc_version:
-    runs-on: ubuntu-20.04
+  get-version-information:
+    name: Get Version Information
+    runs-on: ubuntu-latest
     outputs:
-      cbmc_version: ${{ steps.cbmc_version_number.outputs.CBMC_VERSION }}
-      bump_git_sha: ${{ steps.commit_bump.outputs.bump_git_sha }}
+      version: ${{ steps.split.outputs._2 }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: jungwinter/split@v1
+        id: split
         with:
-          submodules: recursive
-      - name: Get new CBMC version number
-        id: cbmc_version_number
-        run: |
-          NEW_CBMC_VERSION=$(grep '^CBMC_VERSION =' src/config.inc | cut -d = -f 2 | scripts/increment_version.sh)
-          echo ::set-env name=CBMC_VERSION::$NEW_CBMC_VERSION
-          echo ::set-output name=CBMC_VERSION::$NEW_CBMC_VERSION
-      - name: Update CBMC version
-        run: |
-          sed -i "s/CBMC_VERSION = .*/CBMC_VERSION = $CBMC_VERSION/" src/config.inc
-      - name: Set git identity to github bot
-        run: |
-          git config --local user.name db-ci-cprover
-          git config --local user.email "[email protected]"
-      - name: Commit changes
-        id: commit_bump
-        run: |
-          git commit -a -m "Bump version to $CBMC_VERSION"
-          echo "::set-output name=bump_git_sha::$(git rev-parse HEAD)"
-      - name: Push changes
-        run: |
-          git push
+          msg: ${{ github.ref }}
+          seperator: '/'
   perform-release:
-    needs: bump_cbmc_version
+    name: Perform Release
     runs-on: ubuntu-20.04
+    needs: get-version-information
     steps:
-      - uses: actions/checkout@v2
-        with:
-          # We just added a commit to master, so the default GITHUB_REF doesn’t work anymore
-          ref: master
-      - name: DEBUG show bump version
-        run: echo ${{ needs.bump_cbmc_version.outputs.CBMC_VERSION }}
+      - name: Checkout code
+        uses: actions/checkout@v2
       - name: Create release
         uses: actions/create-release@v1
         env:
           GITHUB_TOKEN: ${{ secrets.DB_CI_CPROVER_ACCESS_TOKEN }}
+          CBMC_TAG: ${{ needs.get-version-information.outputs.version }}
         with:
-          tag_name: cbmc-${{ needs.bump_cbmc_version.outputs.CBMC_VERSION }}
-          release_name: cbmc-${{ needs.bump_cbmc_version.outputs.CBMC_VERSION }}
+          tag_name: ${{ env.CBMC_TAG }}
+          release_name: ${{ env.CBMC_TAG }}
+          body: |
+            This is CBMC version ${{ env.CBMC_TAG }}.
+
+            ## MacOS
+
+            On MacOS, install CBMC using [Homebrew](https://brew.sh/) with
+            ```sh
+            brew install cbmc
+            ```
+
+            or upgrade (if it's already been installed) with:
+
+            ```sh
+            brew upgrade cbmc
+            ```
+
+            ## Ubuntu
+
+            On Ubuntu, install CBMC by downloading the *.deb package below for your version of Ubuntu
+            and install with one of
+
+            ```sh
+            # Ubuntu 18:
+            $ dpkg -i ubuntu-18.04-${{ env.CBMC_TAG }}-Linux.deb
+            # Ubuntu 20:
+            $ dpkg -i ubuntu-20.04-${{ env.CBMC_TAG }}-Linux.deb
+            ```
+
+            ## Windows
+
+            On Windows, install CBMC by downloading the `${{ env.CBMC_TAG }}-win64.msi` installer
+            below, double-clicking on the installer to run it, and adding the folder
+            `C:\Program Files\cbmc\bin` in your `PATH` environment variable.
+
+            For installation from the windows command prompt, run:
+
+            ```sh
+            msiexec /i ${{ env.CBMC_TAG }}-win64.msi
+            PATH="c:\program files\cbmc\bin";%PATH%
+            ```
+
+            Note that we depend on the Visual C++ redistributables. You likely already have these,
+            if not please download and run vcredist.x64.exe from Microsoft to install them prior
+            to running cbmc, or make sure you have Visual Studio 2019 installed.
+
+            You can download either [Visual Studio 2019 Community Edition](https://visualstudio.microsoft.com/vs/community/)
+            or the [Visual C++ Redistributables](https://support.microsoft.com/en-gb/help/2977003/the-latest-supported-visual-c-downloads) from Microsoft for free.
           draft: false
           prerelease: false
-          commitish: ${{ needs.bump_cbmc_version.outputs.bump_git_sha }}

README.md

@@ -43,6 +43,24 @@ already have these, if not please download and run vcredist.x64.exe from
 [Microsoft](https://support.microsoft.com/en-gb/help/2977003/the-latest-supported-visual-c-downloads) to install them prior to running
 cbmc.
 
+### Linux
+
+For different linux environments, you have these choices:
+
+1. Install CBMC through the distribution's repositories, with the downside
+   that this might install an older version of cbmc, depending on what the
+   package maintenance policy of the distribution is, or
+2. Install CBMC through the `.deb` package built by each release, available
+   on the [releases](https://github.com/diffblue/cbmc/releases) page. To
+   do that, download the `.deb` package and run `apt install cbmc-x.y.deb`
+   with `root` privileges, with `x.y` being substituted for the version
+   you are attempting to install.
+
+   *NOTE*: Because of libc/libc++ ABI compatibility and package
+   dependency names, if you follow this path make sure you install the
+   package appropriate for the version of operating system you are using.
+3. Compile from source using the instructions [here](COMPILING.md)
+
 ### macOS
 
 For macOS there is a [Homebrew](https://brew.sh) package

doc/ADR/README.md

@@ -0,0 +1,11 @@
+# Architecture Decision Records
+
+This folder is designated to contain our ADRs (Architecture
+Decision Records) - documentation for why specific decision
+where taken at the time they were, so that future maintainers
+can more easily identify constraints that shaped the architecture
+of the system and the surrounding infrastructure.
+
+## Release & Packaging
+
+* [Release Process](release_process.md)

doc/ADR/release_process.md

@@ -0,0 +1,60 @@
+# Release Process
+
+**Date**: 8-10-2020
+**Author**: Fotis Koutoulakis, [email protected]
+**Domain**: Release & Packaging
+
+## Process
+
+The current process we follow through to make a new release is the following:
+
+1. At the point in time we want to make the release, we make a change to 
+   `src/config.inc`, and update the configuration variable `CBMC_VERSION`.
+   This is important as it informs the various tools of the current version
+   of CBMC.
+
+   (This needs to be pushed as a PR, and after it gets merged we move on to:)
+
+2. Then we make a `git tag` out of that commit, and push it to github. The
+   tag needs to be of the form `cbmc-<version>` with version being a version
+   number of the form of `x.y.z`, with `x` denoting the major version, `y`
+   denoting the minor version, and `z` identifying the patch version (useful
+   for a hotfix or patch.)
+
+At this point, the rest of the process is automated, so we don't need to do
+anything more, but the process is described below for reference:
+
+3. `.github/workflows/regular-release.yaml` gets triggered on the `push`
+   of the tag, and creates a Github release of the version that was
+   described in thetag pushed (so, tag `cbmc-5.15.20` is going to
+   create the release titled `cbmc-5.15.20` on the release page).
+
+4. `.github/workflows/release-packages.yaml` gets triggered automatically
+   at the creation of the release, and its job is to build packages for
+   Windows, Ubuntu 18.04 and Ubuntu 20.04 (for now, we may support more
+   specific Ubuntu versions later) and attaches them (after it has finished
+   building them) to the release page as release artifacts. 
+
+   It also makes a PR to the homebrew repository that updates the version
+   of CBMC in homebrew. That's then approved and merged by the maintainers
+   of homebrew.
+
+## Constraints
+
+Initial design of the release process suggested that the release cadence
+of CBMC was going to be one regular release (incrementing the `y` part
+of the version) every two weeks, on Thursday.
+
+Originally we wanted to automate this part, but we were limited by the
+fact that we needed to update `src/config.inc` before doing the release,
+and that couldn't be done in an automated fashion, as any update needs
+to go through a PR, and gets stuck on code-owners approvals, making the
+whole process more manual than intended.
+
+Following this original limitation, we decided to settle on doing manual
+releases every two weeks, but having the process being initiated by a
+developer manually making the change to `src/config.inc`, and after that
+has been merged, mark that specific commit as with a version tag, and push
+that version tag to Github. At that point, the rest of the process is automated.
+
+The change to the current implementation was part of https://github.com/diffblue/cbmc/pull/5517.