feat: add release workflow, update docs

Author: hnrobert

.github/workflows/package-matrix.yml

@@ -3,9 +3,8 @@ env:
   PIP_DISABLE_PIP_VERSION_CHECK: "1"
 
 on:
-  workflow_dispatch:
-  push:
-    tags: ["v*"]
+  release:
+    types: [published]
 
 jobs:
   package:
@@ -16,6 +15,8 @@ jobs:
         python-version: [3.8, 3.11]
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
@@ -33,3 +34,13 @@ jobs:
         with:
           name: hello-${{ matrix.os }}-${{ matrix.python-version }}
           path: dist/hello-${{ matrix.os }}-${{ matrix.python-version }}*
+
+      - name: Upload artifact to GitHub Release
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            dist/hello-${{ matrix.os }}-${{ matrix.python-version }}*
+          tag_name: ${{ github.event.release.tag_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/package.yml

@@ -12,7 +12,6 @@ jobs:
     steps:
       - name: Check out
         uses: actions/checkout@v4
-
       - name: Show runner arch
         run: uname -m || true
       - name: Setup Python

.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Create Release Tag
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. 1.0.0)."
+        required: true
+        default: "1.0.0"
+
+permissions:
+  contents: write
+
+jobs:
+  create-tag:
+    name: Create and push tag
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate and normalize version input
+        id: normalize
+        run: |
+          set -euo pipefail
+          raw_version="${{ github.event.inputs.version }}"
+          if [ -z "$raw_version" ]; then
+            echo "No version provided. Use workflow_dispatch input 'version'." >&2
+            exit 1
+          fi
+          # strip any leading 'v' or 'V'
+          normalized=$(echo "$raw_version" | sed -E 's/^[vV]//')
+          if [ -z "$normalized" ]; then
+            echo "Provided version '$raw_version' is invalid after stripping leading 'v' — please supply a semantic version like 1.2.3." >&2
+            exit 1
+          fi
+          # simple semver-like warning (not fully strict), continue even if it doesn't match
+          if ! echo "$normalized" | grep -E -q '^[0-9]+(\.[0-9]+){1,2}([-.+][0-9A-Za-z.-]+)?$'; then
+            echo "Warning: version '$normalized' doesn't look like semver (X.Y or X.Y.Z). Continuing anyway." >&2
+          fi
+          tag="v${normalized}"
+          echo "Normalized version: $normalized"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Confirm tag does not already exist
+        run: |
+          tag=${{ steps.normalize.outputs.tag }}
+          echo "Checking if tag $tag exists on origin..."
+          if git ls-remote --tags origin | grep -q "refs/tags/$tag"; then
+            echo "Tag $tag already exists on origin — aborting to avoid overwriting." >&2
+            exit 1
+          fi
+
+      - name: Create annotated tag and push to origin
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          tag=${{ steps.normalize.outputs.tag }}
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          echo "Creating annotated tag $tag"
+          git tag -a "$tag" -m "Release $tag"
+          # Set remote URL that uses the token to push the new tag
+          remote_url="https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}"
+          git remote set-url origin "$remote_url"
+          git push origin "$tag"
+
+      - name: Create GitHub release for the tag
+        uses: actions/create-release@v1
+        with:
+          tag_name: ${{ steps.normalize.outputs.tag }}
+          release_name: "Release ${{ steps.normalize.outputs.tag }}"
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -10,20 +10,29 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      # Checkout the repository - Add this step at the beginning of the steps to help the Job access the code
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+      
+      # Set up Python environment - Automatically install Python for the job efficiently
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
           python-version: "3.11"
+
+      # Install dependencies - Install the required packages for testing and linting
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
+
+      # Run linting - Check code style using autopep8
       - name: Run autopep8 check
         run: |
           pip install autopep8
           autopep8 --diff --recursive app tests
 
+      # Run tests - Execute the test suite using pytest. If everything passes, the job will succeed, else it will fail and report the issues
       - name: Run tests
         env:
           PYTHONPATH: ${{ github.workspace }}

README.md

@@ -32,7 +32,7 @@ ls -la dist
 On Windows PowerShell:
 
 ```powershell
-py -3 -m venv .venv
+python -m venv .venv
 .\.venv\Scripts\Activate.ps1
 .venv\Scripts\pip.exe install -r requirements.txt
 .venv\Scripts\pyinstaller.exe --onefile app/hello.py
@@ -45,10 +45,28 @@ You can try implement a simple sequential workflow that first builds macOS arm64
 
 If you have finished composing or encountered some troubles, you may see `solutions/package.yml` — this builds the two packages in sequence and uploads two artifacts (`hello-macos-arm64` and `hello-windows-x64`).
 
-There is also a enhanced version that uses a matrix to build multiple Python versions and OSes in parallel in `solutions/package-matrix.yml`. You may check it out after finishing the exercise.
+There is also a enhanced version that uses a matrix to build multiple Python versions and OSes in parallel in `.github/workflows/package-matrix.yml`. You may check it out after finishing the exercise.
 
 Steps:
 
 1. Copy `solutions/package.yml` into `.github/workflows/package.yml`.
 2. Commit and push; this will trigger the workflow via `workflow_dispatch` if you run it manually, or on `push` tags.
 3. Check the workflow run and download artifacts from the run summary.
+
+## Release flow (automatic packaging and release assets)
+
+The repository includes a pair of workflows to create a tag, publish a release, and attach build artifacts to the release:
+
+- `release.yml` — creates a `vX.Y.Z` tag from the workflow_dispatch input and publishes a GitHub Release.
+- `package-matrix.yml` — runs packaging on `ubuntu`, `macos`, and `windows` using a matrix and attaches the build artifacts to the release when the workflow is triggered by the `release` event.
+
+How it works:
+
+1. Use the **Create Release** workflow in the Actions tab.
+2. The workflow will create the tag base on your input and publish the release; this publishes a `release` event.
+3. `package-matrix.yml` is configured to run when a release is published; it will build packages for each OS/Python combination in the matrix and attach each artifact to the release.
+
+Notes:
+
+- The build artifacts are attached to the Release created by `release.yml`.
+- Packaging is also possible manually by running the `Package — Build & Upload using Matrix` workflow.