Create draft GitHub release automatically when a v* tag is pushed

.github/workflows/matlab.yml

@@ -83,13 +83,19 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Set up MATLAB
         uses: matlab-actions/setup-matlab@v3
         with:
           release: latest
           cache: true
 
+      - name: Set toolbox version from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: echo "TOOLBOX_VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"
+
       - name: Build toolbox
         uses: matlab-actions/run-build@v3
         with:
@@ -100,3 +106,45 @@ jobs:
         with:
           name: MATLAB_Toolbox_for_TOML_and_YAML.mltbx
           path: release/MATLAB_Toolbox_for_TOML_and_YAML.mltbx
+
+  release:
+    runs-on: ubuntu-latest
+    needs: package
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Only release commits that have been merged to main.
+      - name: Verify tag is on main
+        run: |
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::Tag $GITHUB_REF_NAME ($GITHUB_SHA) is not on main."
+            exit 1
+          fi
+
+      - name: Download toolbox artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: MATLAB_Toolbox_for_TOML_and_YAML.mltbx
+
+      # Create a draft; an admin reviews and publishes it (published releases are immutable).
+      - name: Create draft GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" MATLAB_Toolbox_for_TOML_and_YAML.mltbx \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            --draft
+          {
+            echo "Draft release created for \`$GITHUB_REF_NAME\`. Verify the asset digest before publishing:"
+            echo '```'
+            sha256sum MATLAB_Toolbox_for_TOML_and_YAML.mltbx
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

CONTRIBUTING.md

@@ -47,5 +47,19 @@ All work must be done on a branch, not on main. Create a new branch for new work
 - Run `buildtool test` and verify that code coverage has not regressed compared to the base branch.
 - Before starting work on an issue, review all open and closed issues, discussions, and other open branches to check for prior work, related decisions, or overlapping efforts.
 
+## Releasing
+**Repository admins only.** A tag ruleset restricts tag creation to admins.
+
+1. Tag the release commit on `main` and push the tag. The toolbox version comes from the tag.
+   ```
+   git checkout main && git pull
+   git tag v0.1.5
+   git push origin v0.1.5
+   ```
+2. CI runs the tests, packages the `.mltbx`, and creates a **draft** release.
+3. Open the draft under **Releases**. Check that the `.mltbx` digest matches the SHA-256 in the `release` job summary, edit the notes if needed, and click **Publish**.
+
+Published releases are immutable, and their version cannot be reused. If the draft is wrong, delete the draft and the tag (`git push origin :v0.1.5`), fix the issue, and tag again.
+
 
 **Again, thanks for contributing, and we look forward to your issues and pull requests!**

buildfile.m

@@ -68,7 +68,7 @@ function mltbxTask(~)
     if ~isMATLABReleaseOlderThan("R2026b")
         opts.PackageName = "tomlyaml";
     end
-    opts.ToolboxVersion = "0.1.4";
+    opts.ToolboxVersion = toolboxVersion();
     opts.MinimumMatlabRelease = "R2022b";
     opts.OutputFile = fullfile("release", "MATLAB_Toolbox_for_TOML_and_YAML.mltbx");
     opts.Summary = "Read and write TOML and YAML configuration files with dot notation access.";
@@ -80,6 +80,22 @@ function mltbxTask(~)
     matlab.addons.toolbox.packageToolbox(opts);
 end
 
+function versionNumber = toolboxVersion()
+    % Toolbox version: TOOLBOX_VERSION (set by CI from the pushed tag), else
+    % the most recent vX.Y.Z git tag. Errors if neither is available.
+    versionNumber = string(getenv("TOOLBOX_VERSION"));
+    if versionNumber ~= ""
+        return
+    end
+    [status, output] = system("git describe --tags --abbrev=0 --match ""v[0-9]*""");
+    if status ~= 0
+        error("buildfile:NoToolboxVersion", ...
+            "Unable to determine toolbox version. Set TOOLBOX_VERSION " + ...
+            "or run from a git checkout with vX.Y.Z tags.\ngit: %s", strtrim(output));
+    end
+    versionNumber = extractAfter(strtrim(string(output)), "v");
+end
+
 %% ---- Formatting and static analysis ----------------------------------------
 
 function indentTask(~)