Merge pull request #94 from hytest-org/dev

.github/workflows/How_To_Release.md

@@ -0,0 +1,63 @@
+# How to publish a new HyTEST release
+
+## Essential Steps
+
+* Make `dev` branch look like you want.
+  * Merge various feature branches in to `dev` with PRs (or not... manually also works; PR preferred)
+  * Direct commits to `dev` are also OK (but discouraged)
+  * edit the `environment_set_up/manifest.txt` to reflect what you want in the bootstrap archive (see
+    below: "What's In the Archive").
+  * NOTE: you are not obligated to use `dev` -- it is just a convenient place to assemble multiple
+    feature branches to ensure they work together. The rest of this workflow will still operate.
+    The auto-bundling will fire with **any** merge into `main`, whether from `dev` or not.
+* Create a PR to merge `dev` into `main`
+  * Use github **Labels** to identify how you want the [Semantic Version](https://semver.org/) to increment:
+    - No labels, increments the _patch_ number (the _p_ in 'M.m.p')<br>
+      Patch updates are usually associated with minor changes meant to address problems or bugs.
+    - Label "SemVer::Minor++" increments the _minor_ number (the _m_ in 'M.m.p')<br>
+      A minor update includes more impactful changes, but none of them are "breaking" changes -- meaning
+      that a user doesn't have to change their behavior to use the new version... changes don't break
+      the user experience.
+    - Label "SemVer::Major++" increments the _major_ number (the M in 'M.m.p').<br>
+      Major version increments are typically associated with "breaking" changes, where the user has
+      to change how they use the tool (it is 'broken' if they don't change). Example.. the change from
+      Python 2.7 to 3.x includes breaking changes -- the nature of fundamental operations is different
+      (e.g. the 'print' built-in works differently and is invoked differently between 2.x and 3.x)
+  * These labels already exist in the repo... just apply as appropriate to reflect how
+    you want the version number to increment for this new release.
+* PR can be approved / reviewed / updated... with last-second changes merged into `dev`
+* Merge `dev` into `main` **with a Pull Request**
+  * The [github action](./release-on-pr-merge-to-main.yml) fires with this specific set of
+    conditions.  A manual merge to main will not trigger.
+  * Observe the run by examining the 'Actions' tab in the repo. If the action fails for some
+    reason, this is where you will look for the logs and other debug information.
+
+Upon a successful run, you should now see a new [release](https://github.com/hytest-org/hytest/releases).
+Releases will be available indefinitely by referring to their GitHub **tag**, which is created
+as a part of this github action.  Tags are Semantic Version numbers, preceeded with a 'v' (e.g. 'v1.2.1').
+A git release is available via its version number:
+
+```text
+https://github.com/hytest-org/hytest/releases/v1.2.1
+```
+
+You can always point to the 'latest' release with the URL:
+
+```text
+https://github.com/hytest-org/hytest/releases/latest/
+```
+
+The direct link to the downloadable archive of setup materials is available with the URL:
+
+```text
+https://github.com/hytest-org/hytest/releases/latest/download/HyTEST_EnvSetUp.tar.gz
+```
+
+## What's in the Archive
+
+The contents of the archive are intended to support the environment set up documented in our
+[QuickStart for HPC](../../environment_set_up/QuickStart-HPC.md). The specific files included are
+determined by the contents of the `environment_set_up/manifest.txt` file.
+Put file names (one per line) in this file to see that they are included in the released archive.
+The manifest file supports **simple** comments.  A `#` **as the first character** will cause
+that line to be ignored.  One file per line, with a path name relative to the base of the repo.

.github/workflows/release-on-pr-merge-to-main.yml

@@ -0,0 +1,133 @@
+name: Build a release and increment SemVer upon pr/merge to main branch
+
+# Note, the version string is not tracked in a file within the repo.  The version
+# is assumed to be associated with git tags formated like SemVer versions. 
+#
+# The eregex I am using for a 'valid' SemVer is: [Vv]?(\d+)\.(\d+)\.(\d+)
+#   - optional leading v (or V)
+#   - Number(s)
+#   - a dot
+#   - Number(s)
+#   - a dot
+#   - Number(s)  
+#
+# This is a simplified version of the regex offered at https://semver.org/
+# Also note that I am allowing the optional leading [vV] to scan for tags,
+# while semver.org says no. This is mostly to do with making it easy to store 
+# the SemVer as a tag (which would be nice to include the leading 'v').
+
+# The routine to increment SemVer will assess which part of the version to 
+# increment based on labels associated with the PR.  These labels have 
+# specific names: 
+#   - 'SemVer:Major++' == Bump the Major part of the SemVer
+#   - 'SemVer:Minor++' == Bump the Minor part of the SemVer
+# If neither of those labels are found on the PR, then the patch number 
+# is incremented. 
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches: [ "main" ]
+
+env:
+    ZIPNAME: HyTEST_EnvSetUp.tar.gz     #<<<<<<<< IMPORTANT !!!
+    ## See the 'makezip' step below
+
+jobs:
+  release-on-pr-merge-to-main:
+
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: Fetch the last SemVer-formatted tag
+        id: lastver
+        uses: actions/github-script@v6
+        with:
+          result-encoding: string
+          script: |
+            function refFilter(cmp) {
+              return /\/[Vv]?(\d+)\.(\d+)\.(\d+)$/.test(cmp.ref)
+            }
+            function semVerCmp(a, b) {
+              const A = a.split('.'); const B = b.split('.')
+              return (A[0]*10000 + A[1]*100 + A[2]) - ( B[0]*10000 + B[1]*100 + B[2])
+            }
+            let taggedVer = await github.paginate(github.rest.git.listMatchingRefs, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: 'tags/v'
+            }).then( reflist => {
+              const taglist = reflist.filter(refFilter).map(function(r) {return r.ref.slice(r.ref.search(/\d/))}).sort(semVerCmp)
+              if (taglist.length == 0) { return "0.0.0" }
+              return taglist.pop()
+            });
+            return taggedVer
+
+      - name: Increment SemVer based on labels in the PullRequest
+        id: nextver
+        uses: actions/github-script@v6
+        env:
+          VER: ${{ steps.lastver.outputs.result }}
+        with:
+          result-encoding: string
+          script: |
+            function semVer_PlusPlus(v, Mmp) {
+              const V = v.split('.');
+                switch (Mmp.toUpperCase()){
+                    case "MAJOR": return `${Number(V[0])+1}.0.0` ;
+                    case "MINOR": return `${V[0]}.${Number(V[1])+1}.0` ;
+                    default: return `${V[0]}.${V[1]}.${Number(V[2])+1}` ;
+                }
+            }
+            const labelList = context.payload.pull_request.labels.map(l => {return l.name})
+            if (labelList.includes('SemVer:Major++')){
+              return semVer_PlusPlus(process.env.VER, 'major')
+            }
+            if (labelList.includes('SemVer:Minor++')){
+              return semVer_PlusPlus(process.env.VER, 'minor')
+            }
+            return semVer_PlusPlus(process.env.VER, 'patch')
+
+      - name: Create a release tagged with incremented SemVer
+        uses: actions/create-release@v1
+        id:   createrelease
+        env: 
+          GITHUB_TOKEN: ${{ github.token }}
+        with: 
+          draft: false
+          prerelease: false
+          release_name: "v${{ steps.nextver.outputs.result }}"
+          tag_name: "v${{ steps.nextver.outputs.result }}"
+
+      - name: tar/Zip a sanitized version of this repo
+        id:   makezip
+        # This step is a simple sanitizing and archiving of the repo dir.  
+        # If you would like to do something more complex, it would be good to 
+        # do those more complicated actions via Makefile or similar. Whatever
+        # the mechanism, you'll also need to adjust the 'uploadzip' step below
+        # to reflect the path and filename of the artifact/asset to bind to 
+        # this release.
+        run: |
+          echo ${{ steps.nextver.outputs.result }} > VERSION
+          cd ../
+          dname=`basename ${GITHUB_REPOSITORY}`
+          echo "Creating ZIP archive:  ${ZIPNAME}"
+          # Sanitize manifest:  remove comments (leading '#'), remove trailing whitespace
+          sed -e '/^#/d' -e "s!^!./${dname}/!" -e 's/\s*$//' < ${dname}/environment_set_up/manifest.txt > /tmp/manifest.txt
+          tar --files-from /tmp/manifest.txt -cvf - | gzip > /tmp/${ZIPNAME}
+
+
+      - name: Upload ZIP package and bind to release.
+        id:   uploadzip
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        with:
+          upload_url: ${{ steps.createrelease.outputs.upload_url }}
+          asset_path: "/tmp/${{ env.ZIPNAME }}"
+          asset_name: ${{ env.ZIPNAME }}
+          asset_content_type: application/zip

.gitignore

@@ -1,3 +1,4 @@
+
 # python chaff...
 __pycache__/
 *.py[cod]