ci: add manual trigger, update readme from code.json

.github/workflows/continuous_integration.yml

@@ -6,6 +6,7 @@ on:
   push:
     branches: [ master ]
   pull_request:
+  workflow_dispatch:
 jobs:
   executables-intel:
     name: pymake CI intel on different OSs
@@ -46,9 +47,6 @@ jobs:
           python -m pip install --upgrade pip
           pip install wheel
           pip install https://github.com/modflowpy/pymake/zipball/master
-
-      - name: Print Python package versions
-        run: |
           pip list
 
       - name: build executables on Linux and macOS
@@ -78,7 +76,6 @@ jobs:
             ./code.json
             ./code.md
 
-
   # make the release if previous job was successful
   release:
     name: Make a release
@@ -89,40 +86,48 @@ jobs:
         shell: bash
 
     steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: 3.9
 
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install https://github.com/modflowpy/pymake/zipball/master
+
       - name: Get the latest release tag
         uses: oprypin/find-latest-tag@v1
         with:
           repository: MODFLOW-USGS/executables  # The repository to scan.
           releases-only: true  # We know that all relevant tags have a GitHub release for them.
         id: executables  # The step ID to refer to later.
 
-      - name: Set latest release tag as a environment variable
+      - name: Get latest release tag
         run: |
           current="${{ steps.executables.outputs.tag }}"
           # next="${current%.*}.$((${current##*.}+1))"
           next=$(echo "${{ steps.executables.outputs.tag }} + 1.0" | bc)
           echo "RELEASE_VERSION=$current" >> $GITHUB_ENV
           echo "NEXT_VERSION=$next" >> $GITHUB_ENV
-          echo "MODFLOW-USGS/executables current version is $current"
-          echo "MODFLOW-USGS/executables next version is $next"
+          
+          repo="${{ github.repository }}"
+          echo "$repo current version is $current"
+          echo "$repo next version is $next"
 
-      - name: Download a Build Artifact
+      - name: Download release artifact
         uses: actions/[email protected]
         with:
           name: release_build
           path: ./release_build/
 
-      - name: List files in the artifact directory
-        run: |
-          pwd
-          ls -l ./release_build/
+      - name: List artifact files
+        run: ls -l ./release_build/
 
-      - name: Create the Header for BodyFile markdown file
+      - name: Create release body header
         shell: python
         run: |
           import os
@@ -133,18 +138,59 @@ jobs:
           with open('Header.md', "w") as file:
               file.write(line)
 
-      - name: Build of BodyFile.md
+      - name: Build release body
         run: |
           cat Header.md
-
-      - name: List contents of BodyFile.md
-        run: |
           cat Header.md ./release_build/code.md > BodyFile.md
           cat BodyFile.md
-          rm ./release_build/code.md
 
-      - name: Create a Release
-        if: github.event_name == 'push'
+      - name: Update readme
+        id: update-readme
+        run: |
+          cp release_build/code.md code.md
+          cp release_build/code.json code.json
+          python update_readme.py
+          stat README.md
+          cat README.md
+          readme_changed=$(git diff --exit-code README.md)
+          if [ "$readme_changed" -eq "1" ]; then
+            echo "Changes to README.md:"
+            git diff README.md
+            changes="true"
+          else
+            echo "No changes to README.md"
+            changes="false"
+          fi
+          echo "changes=$changes" >> $GITHUB_OUTPUT
+
+      - name: Draft pull request
+        # only open PR on manual trigger
+        if: github.event_name == 'workflow_dispatch' && steps.update-readme.outputs.changes == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # commit and push
+          branch="update-readme-${{ env.NEXT_VERSION }}"
+          git config core.sharedRepository true
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git status
+          git switch -c $branch
+          git commit -m "ci(release): update readme"
+          git push -u origin "$branch"
+          
+          # create PR
+          body='
+          # MODFLOW executables release '${{ env.NEXT_VERSION }}'
+          
+          This PR updates `README.md` with the latest release information.
+          '
+          gh pr create -B "master" -H "$branch" --title "Release ${{ env.NEXT_VERSION }}" --draft --body "$body"
+
+      - name: Create release
+        # only create new release on manual trigger
+        if: github.event_name == 'workflow_dispatch'
         uses: ncipollo/[email protected]
         with:
           tag: ${{ env.NEXT_VERSION }}

DEVELOPER.md

@@ -0,0 +1,57 @@
+# Developers
+
+This document provides guidance for developers to use this repository to release USGS executables.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Overview](#overview)
+- [Triggering a release](#triggering-a-release)
+  - [GitHub UI](#github-ui)
+  - [GitHub CLI](#github-cli)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Overview
+
+This repository only builds USGS programs and contains none of their source code. Its contents are concerned only with the build and release process. Repository contents have no direct relationship to release cadence or version/tag numbers.
+
+As such, this repo's CI is configured to allow manually triggering releases, independent of changes to version-controlled files.
+
+The `.github/workflows/continuous_integration.yml` CI workflow is triggered on the following events:
+
+- `push` to `master`
+- `pull_request` to any branch
+- `workflow_dispatch`
+
+If the triggering event is a `push` or `pull_request`, binaries are built and uploaded as artifacts, then the workflow ends. If the triggering event is a `workflow_dispatch`, binaries are built and uploaded as artifacts, then a release is created, incrementing the version number. The release is *not* a draft, and is published immediately. If changes are detected to any of the program versions or timestamps, a draft PR is opened against the `master` branch to update the table in `README.md`.
+
+**Note:** version numbers do not currently follow semantic versioning conventions. We simply increment an integer version number by 1 for each release.
+
+## Triggering a release
+
+The `workflow_dispatch` event is GitHub's mechanism for manually triggering workflows. This can be accomplished from the Actions tab in the GitHub UI, or via the [GitHub CLI](https://cli.github.com/manual/gh_workflow_run).
+
+### GitHub UI
+
+Navigate to the Actions tab of this repository. Select the `executables continuous integration` workflow. A `Run workflow` button should be visible in an alert at the top of the list of workflow runs. Click the `Run workflow` button, selecting the `master` branch. 
+
+### GitHub CLI
+
+Install and configure the [GitHub CLI](https://cli.github.com/manual/) if needed. Then the following command can be run from the root of your local clone of the repository:
+
+```shell
+gh workflow run continuous_integration.yml
+```
+
+On the first run, the CLI will prompt to choose whether the run should be triggered on your fork of the repository or on the upstream version. This decision is stored for subsequent runs &mdash; to override it later, use the `--repo` (short `-R`) option to specify the repository. For instance, if you initially selected your fork but would like to trigger a release on the main repository:
+
+```shell
+gh workflow run continuous_integration.yml -R MODFLOW-USGS/executables
+```
+
+**Note:** by default, workflow runs are associated with the repository's default branch. If the repo's default branch is `develop` (as is currently the case for `MODFLOW-USGS/executables`, you will need to use the `--ref` (short `-r`) option to specify the `master` branch when triggering a release from the CLI. For instance:
+
+```shell
+gh workflow run continuous_integration.yml -R MODFLOW-USGS/executables -r master
+```

README.md

@@ -1,6 +1,6 @@
 # MODFLOW EXECUTABLES
 
-The purpose of this repository is to distribute binary executable programs for MODFLOW and related programs that will run on Windows, Mac, and Linux operating systems. These programs are compiled using [pymake](https://github.com/modflowpy/pymake) and the Intel OneAPI compilers. The release also includes a json file ([code.json](https://github.com/MODFLOW-USGS/executables/releases/latest/download/code.json)) that includes the current version number and the url address that can be used to download the source files used to build these programs. 
+The purpose of this repository is to distribute binaries for MODFLOW and related programs. Distributions are provided for Windows, Mac, and Linux operating systems. Programs are compiled using [pymake](https://github.com/modflowpy/pymake) and Intel OneAPI compilers. The release also includes a json file [`code.json`](https://github.com/MODFLOW-USGS/executables/releases/latest/download/code.json) that includes, for each program, the current version number, the URL that can be used to download the source files, and the date sources were last updated. A markdown version of this file, `code.md` is also included in the distribution.
 
 Executables for these different operating systems can be found under the [release](https://github.com/MODFLOW-USGS/executables/releases) tab above and are named: