Add scripts/interactive-release.sh for automated releases (IntersectM…

…BO#6748)

.github/workflows/broken-links.yml

@@ -1,9 +1,12 @@
 # This job checks for broken links in various files in the repo.
+#
+# This job runs on all pull requests and on push to master, and it can also be triggered manually.
+
 
 name: "🔗 Broken Links"
 
 on:
-  workflow_dispatch: # Or manually dispatch the job
+  workflow_dispatch: 
   pull_request:
   push:
     branches:

.github/workflows/cabal-build-all.yml

@@ -1,8 +1,11 @@
-# This workflow runs `cabal build all` on Linux with all supported GHC versions.
+# This job runs `cabal build all` on Linux with all supported GHC versions.
 # Normally, if Nix can build the shell and the packages via haskell.nix, we can be confident that 
 # Cabal can build the project inside the Nix shell.
 # However, this workflow is implemented to catch edge cases, such as the one described in 
 # https://github.com/IntersectMBO/plutus/issues/6625.
+#
+# This job runs on all pull requests and on push to master, and it can also be triggered manually.
+
 
 name: "👷 Cabal Build All"
 
@@ -24,7 +27,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@main
 
-      - name: Cold Build On ${{ matrix.ghc }}
+      - name: Cold Build / ${{ matrix.ghc }} / x86_64-linux
         run: | 
           nix develop --no-warn-dirty --accept-flake-config .#${{ matrix.ghc }} \
             --command bash -c 'cabal clean && cabal update && cabal build all' 

.github/workflows/cardano-constitution-tests.yml

@@ -1,11 +1,14 @@
-# This workflow runs the nighlty cardano-constitution tests 
+# This job runs the nightly cardano-constitution tests.
+#
+# This job runs daily at 2am, and it can also be triggered manually.
+
 
 name: "🗽 Cardano Constitution Tests"
 
 on:
   workflow_dispatch: 
   schedule:
-    - cron: 0 2 * * * # Daily at 2am
+    - cron: 0 2 * * * 
 
 jobs:
   run:

.github/workflows/changelog-label.yml

@@ -1,6 +1,9 @@
 # This job enforces that: either some changelog.d/** files were added by the 
 # PR, or the PR has the "No Changelog Required" label.  
-
+# 
+# This job runs on all pull requests, and on pull request label changes.
+
+
 name: "🏷️ Changelog Label"
 
 on:

.github/workflows/cost-model-benchmark.yml

@@ -1,12 +1,14 @@
-# This workflow runs the cost model benchmark and uploads the results as a 
-# GitHub artifact.
+# This job runs the cost model benchmark and uploads the results as a GitHub artifact.
+#
+# This job must be triggered manually via workflow dispatch.
+
 
 name: "💰 Cost Model Benchmark" 
 
 on:
   workflow_dispatch:
     inputs:
-      entra-bench-args:
+      extra-bench-args:
         description: 'extra argument(s) to pass to the cost-model-budgeting-bench command'
         default: ''
         type: string
@@ -21,7 +23,7 @@ jobs:
         uses: actions/checkout@main
 
       - name: Run Benchmark
-        run: nix --accept-flake-config run .#cost-model-budgeting-bench -- --csv results.csv ${{ inputs.entra-bench-args }}
+        run: nix --accept-flake-config run .#cost-model-budgeting-bench -- --csv results.csv ${{ inputs.extra-bench-args }}
 
       - name: Upload Results
         uses: actions/upload-artifact@main

.github/workflows/docusaurus-site.yml

@@ -1,7 +1,10 @@
-# This workflow builds the Docusaurus site on pull_request.
-# It also publishes the site on push to master to:
+# This job builds and deploys the Docusaurus site.
+# 
+# This job builds the site on pull requests, and it also automatically deploys 
+# the site on push to master or on workflow dispatch to: 
 # https://plutus.cardano.intersectmbo.org/docs
 
+
 name: "🦕 Docusaurus Site" 
 
 on:
@@ -28,7 +31,7 @@ jobs:
         run: nix develop --no-warn-dirty --accept-flake-config --command bash -c 'yarn && yarn build'
 
       - name: Deploy Site 
-        if: github.event_name == 'push'
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
         uses: JamesIves/github-pages-deploy-action@v4.7.2
         with:
           folder: doc/docusaurus/build

.github/workflows/haddock-site.yml

@@ -1,16 +1,27 @@
-# This workflow builds and publishes the Haddock site to:
-# https://plutus.cardano.intersectmbo.org/haddock/$version
-# And optionally to:
+# This job builds and deploys the Haddock site.
+# 
+# When this job is triggered manually via workflow dispatch, it builds and then 
+# publishes the site according to the 'ref' input:
+# https://plutus.cardano.intersectmbo.org/haddock/$ref
+# And optionally (if the 'latest' flag is set) to: 
 # https://plutus.cardano.intersectmbo.org/haddock/latest
-# On push to master, this workflows publishes to:
+#
+# This job also builds and publishes the site on push to master to:
 # https://plutus.cardano.intersectmbo.org/haddock/master
+#
+# This job does not trigger on each pull request because it takes about 1h to run.
+# However it will build (but not deploy) the site on pull requests to the release/* branches.
+
 
 name: "📜 Haddock Site"
 
 on:
   push: 
     branches:
       - master
+  pull_request:
+    branches:
+      - 'release/*'
 
   workflow_dispatch:
     inputs:
@@ -72,6 +83,7 @@ jobs:
 
       - name: Deploy Site
         uses: JamesIves/github-pages-deploy-action@v4.7.2
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
         with:
           folder: _haddock
           target-folder: haddock/${{ inputs.destination || github.ref_name }}

.github/workflows/longitudinal-benchmark.yml

@@ -1,18 +1,21 @@
-# This workflow runs the benchmarks defined in the environment variable BENCHMARKS.
-# It will collect and aggreate the benchmark output, format it and feed it to the
-# github-action-benchmark action.
-#
+# This job runs a suite of benchmarks and detects performance regressions.
 # The benchmark charts are live at https://plutus.cardano.intersectmbo.org/dev/bench
 # The benchmark data is available at https://plutus.cardano.intersectmbo.org/dev/bench/data.js
 #
-# This is a performance regression check that is run on every push master.
+# This job runs on push to master, and on pull requests to the release/* branches,
+# and it can also be triggered manually.
+
 
 name: "🩺 Longitudinal Benchmark"
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - master
+  pull_request:
+    branches:
+      - 'release/*'
 
 permissions:
   # Deployments permission to deploy GitHub pages website
@@ -34,7 +37,7 @@ jobs:
         run: nix develop --no-warn-dirty --accept-flake-config --command bash ./scripts/run-longitudinal-benchmarks.sh
 
       # We need this otherwise the next step will fail with:
-      # `pre-commit` not found.  Did you forget to activate your virtualenv?
+      # `pre-commit` not found. Did you forget to activate your virtualenv?
       # This is because github-action-benchmark will call git commit outside nix develop.
       - name: Disable Git Hooks
         run: git config core.hooksPath no-hooks

.github/workflows/manual-benchmark.yml

@@ -1,8 +1,11 @@
-# This workflows checks for comments in PRs. If the comment has this format: 
-# /benchmark NAME
-# Then this action will run the benchmark with the given NAME, first against 
+# This job runs the desired benchmarks on demand.
+#
+# This job triggers whenever a comment is created in any PR.
+# If the comment has this format: "/benchmark NAME"
+# The this job will run the benchmark with the given NAME, first against 
 # the current branch and then comparing the results against the master branch.
 
+
 name: "🚀 Manual Benchmark"
 
 on:

.github/workflows/metatheory-site.yml

@@ -5,6 +5,18 @@
 # On push to master, this workflows publishes to:
 # https://plutus.cardano.intersectmbo.org/metatheory/master
 
+# This job builds and deploys the Metatheory site.
+# 
+# When this job is triggered manually via workflow dispatch, it builds and then 
+# publishes the site according to the 'ref' input:
+# https://plutus.cardano.intersectmbo.org/metatheory/$version
+# And optionally (if the 'latest' flag is set) to: 
+# https://plutus.cardano.intersectmbo.org/metatheory/latest
+#
+# This job also builds and publishes the site on push to master to:
+# https://plutus.cardano.intersectmbo.org/metatheory/master
+
+
 name: "🔮 Metatheory Site"
 
 on:

.github/workflows/nightly-testsuite.yml

@@ -1,15 +1,18 @@
-# This workflow runs the nightly plutus-core-test and plutus-ir-test test suite.
+# This job runs the nightly plutus-core-test and plutus-ir-test test suite.
+#
+# This job runs daily at midnight, and it can also be triggered manually.
+
 
 name: "🌘 Nightly Testsuite"
 
 on:
   schedule:
-    - cron: 0 0 * * * # Daily at midnight
+    - cron: 0 0 * * *
 
   workflow_dispatch: 
     inputs:
       hedgehog-tests:
-        description: Numer of tests to run (--hedgehog-tests XXXXX)
+        description: Number of tests to run (--hedgehog-tests XXXXX)
         required: false
         default: "100000"
 

.github/workflows/papers-and-specs.yml

@@ -1,5 +1,7 @@
-# This job builds various papers and deploys them to:
-# https://plutus.cardano.intersectmbo.org/resources
+# This job builds and deploys various papers.
+# 
+# This job runs on all push to master and can also be triggered manually.
+# It deploys the artifacts to: https://plutus.cardano.intersectmbo.org/resources
 
 name: "📝 Papers & Specs"
 

.github/workflows/plutus-tx-template.yml

@@ -1,9 +1,13 @@
-# This workflows ensures that the plutus-tx-template repository stays working
-# even if there are changes in plutus. It checks out both the current commit of
-# plutus and the master branch of plutus-tx-template. Then, it creates a
-# cabal.project.local for plutus-tx-template that adjusts the plutus version.
-# Finally, it double-checks that everything still builds correctly using cabal
-# inside the devx shell.
+# This job builds the plutus-tx-template using the current version of the plutus code.
+# 
+# It ensures that the plutus-tx-template repository stays working even if there 
+# are changes in plutus. It checks out both the current commit of plutus and the 
+# master branch of plutus-tx-template. Then, it creates a cabal.project.local for 
+# plutus-tx-template that adjusts the plutus version. Finally, it double-checks 
+# that everything still builds correctly using cabal inside the devx shell.
+#
+# This job runs on all pull requests.
+
 
 name: "🏛️ PlutusTx Template"
 

.github/workflows/slack-message-broker.yml

@@ -1,5 +1,7 @@
-# This workflow sends a message to the plutus-ci channel whenever a status check fails, 
+# This job sends a message to the plutus-ci channel whenever a status check fails, 
 # and tried to notify the author of the commit that caused the failure.
+#
+# This job triggers whenever a workflow run or a check run is completed.
 
 name: "📮 Slack Message Broker"
 

.github/workflows/sprint-issues-rollover.yml

@@ -1,4 +1,4 @@
-# This workflows moves issues and pull requests to the next sprint iteration of 
+# This job moves issues and pull requests to the next sprint iteration of 
 # the Plutus Backlog project. In practice, all open backlog items in the Current
 # Iteration (the one that is still in progress) will be moved to the Next 
 # Iteration (the one that will start next).

.gitignore

@@ -113,3 +113,4 @@ plutus-pab/test-node/alonzo-purple/db
 *.timelog
 *.stacks
 .nvimrc
+release-*

RELEASE.adoc

@@ -31,20 +31,6 @@ A minor release is also allowed to change the observable behaviors of functions
 For example, if a function returns a list of things and makes no promise on the order of elements in the returned list, then a minor release may change the order.
 - A patch release (e.g., 3.5.2.1 -> 3.5.2.2) can only contain such things as simple bug fixes, performance improvements, and documentation updates.
 
-=== Version Qualifiers
-
-Version qualifiers, also known as pre-release versions, usually refer to alpha, beta, and release candidate.
-Typically, alpha and beta are pre-feature complete, while release candidates are post-feature complete.
-
-We do not tag or publish alpha or beta versions for libraries.
-Depending on an alpha or beta version of a library requires `source-repository-package`, which is quite inconvenient.
-It is also uncommon for a library to publish pre-release versions (unless it is new or a complete rewrite).
-
-We do tag release candidates, e.g., 3.5.2.1-rc1, because additional non-CI tests and checks may need to be carried out (see "Release QA Process").
-Tagging release candidates makes it easy to identify the correct commit to run these tests and checks against.
-
-For executables, we may publish alpha, beta or release candidates at our discretion.
-
 == Release Frequency
 
 We will begin by making a new major or minor release every 4 weeks, and evaluate and adjust the frequency in the future.
@@ -55,80 +41,7 @@ In all other cases, we always start a new major or minor release from master.
 
 == Release Process
 
-=== Major and Minor Releases
-
-Suppose we are releasing version `x.y.z.0`.
-
-1. Tag `x.y.z.0-rc1` on master.
-- There's no need to create a release branch at this point.
-A release branch is only needed if bugs are found in `x.y.z.0-rc1` and we need to backport a fix from master.
-- This step can be omitted if no additional tests and checks are needed in the release QA process. See "Release QA Process" below.
-2. In future it will be necessary to run the release QA process (see "Release QA Process" below) at this point, however currently it is not required for the lack of specific instructions.
-3. If no release blocking issue is found, run `./scripts/prepare-release.sh x.y.z.0 <packages>`.
-This updates versions and version bounds, and assembles the changelogs.open a PR for updating the cabal files and the changelog files.
-- `<packages>` should normally be empty, which will prepare the default packages, or can be an explicit list of packages to prepare.
-4. Review the changelogs and edit manually if needed.
-5. Open a PR for updating the cabal files and the changelog files. Example: https://github.com/IntersectMBO/plutus/pull/5452.
-6. Once the PR is merged, 'Draft a new Release' with name `x.y.z.0` using https://github.com/IntersectMBO/plutus/releases/new[Github's release interface] (this can also be found under `Tags`/`Releases` on the main `plutus` page):
-- Choose as git tag `x.y.z.0`
-- Choose as target the git commit hash which points to the release commit
-- Click `Generate release notes` to automatically fill in the details of what's changed
-- Create and attach pir&uplc executables to the release by running the following script inside the repository where its HEAD is at the release commit: `./scripts/prepare-bins.sh`. This will create `pir-x86_64-linux-ghc96` and `uplc-x86_64-linux-ghc96` executables, compress them and put in the project's root folder. Upload them to the release draft.
-- Click `Publish release`.
-7. Open a PR in the https://github.com/IntersectMBO/cardano-haskell-packages[CHaP repository] for publishing the new version. +
-If you are making PR from your own fork then don't forget to sync your fork with the upstream first. +
-Run `./scripts/add-from-github.sh "https://github.com/IntersectMBO/plutus" COMMIT-SHA plutus-core plutus-ledger-api plutus-tx plutus-tx-plugin` (see https://github.com/IntersectMBO/cardano-haskell-packages#-from-github[the README on CHaP]). Example: https://github.com/IntersectMBO/cardano-haskell-packages/pull/764.
-- If issues are found, create a release branch `release/x.y.z`, fix the issues on master, backport the fixes to `release/x.y.z`, tag `x.y.z.0-rc2`, and go to step 4.
-- Why not just fix the issues on master and tag `x.y.z.0-rc2` from master?
-It is desirable to minimize the amount of change between `rc1` and `rc2`, because it may reduce the tests and checks that need to be performed against `rc2`.
-For instance, if `plutus-ledger-api` is the only package changed, there is no need to re-run tests on `plutus-core` or `plutus-tx`.
-Another example is if a security audit is done on `rc1`, and the changes in `rc2` do not modify the audited code, then the audit does not need to be re-done.
-- If another CHaP PR gets merged before yours it will invalidate the timestamps and you won't be able to merge: see the https://github.com/IntersectMBO/cardano-haskell-packages/blob/main/README.md[CHaP README file], in particular https://github.com/IntersectMBO/cardano-haskell-packages/blob/main/README.md#monotonically-increasing-timestamps[this section].  Read https://github.com/IntersectMBO/cardano-haskell-packages/blob/main/README.md#dealing-with-timestamp-conflicts[this section] for advice on how to deal with this problem.
-
-8. Make a PR to update the version used in `plutus-tx-template`
-- Navigate to the https://github.com/IntersectMBO/plutus-tx-template/actions/workflows/bump-plutus-version.yml[Bump Plutus Version Action] on GitHub
-- Click the `Run workflow` button on the right, enter the new release version and confirm
-- This will automatically open a PR in `plutus-tx-template` with auto-merge enabled
-- Ensure that CI is green and the PR gets merged
-
-9. Publish the updated Metatheory site
-- Navigate to the https://github.com/IntersectMBO/plutus/actions/workflows/metatheory-site.yml[Metatheory Site Action] on GitHub
-- Click the `Run workflow` button on the right, enter the new release version 2 times, leave the checkbox Enabled, and confirm
-- Ensure that the action completes successfully
-
-10. Publish the updated Haddock site
-- Navigate to the https://github.com/IntersectMBO/plutus/actions/workflows/haddock-site.yml[Haddock Site Action] on GitHub
-- Click the `Run workflow` button on the right, enter the new release version 2 times, leave the checkbox Enabled, and confirm
-- Ensure that the action completes successfully
-
-11. Delete unused branches and tags
-- If it was created, delete the `release/*` branch locally and on GitHub
-- If they were created, delete any release candidate `-rc*` tags locally and on GitHub
-
-=== Patch Releases
-
-Suppose we are releasing version `x.y.z.w`.
-
-1. If it is the first time we are making a patch release for version `x.y.z` (i.e., `x.y.z.0` -> `x.y.z.1`), a release branch may not exist for `x.y`.
-If so, create branch `release/x.y.z` from the `x.y.z.0` tag.
-- We create release branches lazily, because we do not expect to make many patch releases.
-2. Backport the needed fixes from master to `release/x.y.z`.
-3. Tag `x.y.z.w-rc1` on the release branch.
-- This step can be omitted if no additional tests and checks are needed in the release QA process. See "Release QA Process" below.
-4. Run the release QA process. See "Release QA Process" below.
-5. If no release blocking issue is found, run `./scripts/prepare-release.sh x.y.z.w <packages>`.
-6. Open a PR for updating the cabal files and the changelog files.
-7. Once the PR is merged, tag the commit `x.y.z.w`, and open a PR in the CHaP repository for publishing the new version.
-- If issues are found, fix them on master, backport the fixes to `release/x.y.z`, and go to step 5.
-8. If it was created, delete the `release/*` branch locally and on GitHub
-
-=== Release QA Process
-
-All applicable tests and checks that haven't been run on the release candidate should be carried out prior to tagging and publishing a release.
-- This includes all tests that can be done with only the Plutus repo, such as unit tests, property-based tests, conformance tests and nightly tests.
-- In some cases we need input from domain experts and/or security audit (e.g., when adding a cryptography builtin).
-The right group of people should be involved and sign off on the tests and checks.
-- This does not include tests that require building a new node, or integrating with other downstream projects.
+Run `./scripts/interactive-release.sh` to manage the release process. 
 
 == Backwards Compatibility with Cardano API