docs(release)!: document release process

.github/workflows/ci.yaml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
   push:
     tags-ignore:
-      - "*"
+      - "v*"
     branches-ignore:
       - main
 
@@ -82,8 +82,8 @@ jobs:
       - test
 
     permissions:
-      contents:      read
-      actions:       read  # to download code coverage results from "test" job
+      contents: read
+      actions: read # to download code coverage results from "test" job
       pull-requests: write # write permission needed to comment on PR
 
     steps:
@@ -115,7 +115,7 @@ jobs:
       # Setup tinygo
       - uses: acifani/setup-tinygo@v2
         with:
-          tinygo-version: '0.37.0'
+          tinygo-version: "0.37.0"
 
       # Build fanunit firmware
       - name: Build FanUnit Firmware

.github/workflows/pr-hygiene.yaml

@@ -1,4 +1,4 @@
-name: Pull Request Hygiene
+name: GitHub Pull Request Hygiene
 
 on:
   pull_request:
@@ -39,11 +39,11 @@ jobs:
           header: pr-title-lint-error
           message: |
             Hey there and thank you for opening this pull request! 👋🏼
-            
+
             We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.
 
             Details:
-            
+
             ```
             ${{ steps.lint_pr_title.outputs.error_message }}
             ```
@@ -74,4 +74,4 @@ jobs:
         name: Write step-summary
         run: |
           echo "All Labels: ${{ steps.labeler.outputs.all-labels }}" >> "$GITHUB_STEP_SUMMARY"
-          echo "New Labels for this iteration: ${{ steps.labeler.outputs.new-labels }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "New Labels for this iteration: ${{ steps.labeler.outputs.new-labels }}" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/release.yaml

@@ -1,25 +1,13 @@
-name: Go Build - Release
+name: Go Release - Publish
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
 
 permissions: write-all
 
 jobs:
-  # Release-please for auto-updated PRs
-  release-please:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: google-github-actions/release-please-action@v3
-        id: release-please
-        with:
-          release-type: simple # actual releasing is handled by goreleaser
-          package-name: compute-blade-agent
-          bump-minor-pre-major: true
-    outputs:
-      release_created: ${{ steps.release-please.outputs.release_created }}
-
   test:
     name: Unit Tests
     runs-on: ubuntu-latest
@@ -46,11 +34,31 @@ jobs:
           path: "coverage.txt"
           if-no-files-found: error
 
-  tinygo:
+  # Release-please for auto-updated PRs
+  release-please:
+    name: Release Please
     runs-on: ubuntu-latest
     needs:
       - test
 
+    steps:
+      - uses: googleapis/release-please-action@v3
+        id: release-please
+        with:
+          release-type: simple # actual releasing is handled by goreleaser
+          package-name: compute-blade-agent
+          bump-minor-pre-major: true
+    outputs:
+      release_created: ${{ steps.release-please.outputs.release_created }}
+
+  tinygo:
+    name: Build FanUnit Firmware
+    runs-on: ubuntu-latest
+    needs:
+      - release-please
+
+    if: needs.release-please.outputs.release_created
+
     steps:
       - name: Checkout
         uses: actions/checkout@v4

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Releases
+
+This project uses [release-please](https://github.com/googleapis/release-please) and [goreleaser](https://goreleaser.com/) to automate releases based on conventional commits.
+
+Releases are **semi-automated** and follow this flow:
+
+### 1. Merge Code to `main`
+
+All new features, fixes, and changes are merged into the `main` branch via pull requests using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+Examples:
+
+- `feat: add new API endpoint`
+- `fix: correct off-by-one error`
+- `chore: update dependencies`
+
+### 2. Release PR is Auto-Created
+
+Once a commit is merged into `main`, a GitHub Action runs `release-please`, which:
+
+- Calculates the next version (e.g., `v0.9.1`)
+- Creates a pull request (e.g., `chore: release v0.9.1`)
+- Includes a generated changelog in `CHANGELOG.md`
+
+> 📌 Note:
+> This PR should **not be edited manually**. If something is wrong, fix the commit messages instead.
+
+### 3. Merge the Release PR
+
+Once the release PR is approved and merged:
+
+- The changelog and version bump are committed to `main`
+- `release-please` pushes a new tag with the version-number the merged commit on `main`
+
+### 4. Tag Triggers `goreleaser`
+
+A GitHub Action watches for `v*` tags and runs `goreleaser`, which:
+
+- Builds all binaries and artifacts
+- Publishes them to GitHub Releases
+- Optionally signs and pushes container images (if configured)
+- Attaches additional files (e.g., firmware, config) as release assets
+
+Once complete, the new GitHub Release is available at: [github.com/compute-blade-community/compute-blade-agent/releases](https://github.com/compute-blade-community/compute-blade-agent/releases)
+
+## Notes
+
+- Never push tags manually.
+- Only edit the changelog through conventional commits and `release-please`.
+- You can retry failed releases by deleting the failed tag and re-merging the release PR or re-running the workflow.