Merge pull request #264 from RayforceDB/dev

v2.1.0

Author: singaraiona

.github/workflows/ci.yml

@@ -1,10 +1,18 @@
 name: CI
 
 on:
+  # Pushes: only the dev integration branch needs a standing green signal
+  # (releases are cut from it). Master is intentionally absent — a push to
+  # master only happens via a merged PR, whose pull_request run already
+  # tested the exact merge result, so re-testing post-merge is redundant
+  # (and can't gate anything anyway).
   push:
-    branches: [master]
+    branches: [dev]
+  # PRs into dev AND master are tested. The pull_request->master run tests
+  # dev merged into master and is the check that branch protection requires
+  # to reject a failing release merge — keep it.
   pull_request:
-    branches: [master]
+    branches: [master, dev]
 
 jobs:
   build-and-test:
@@ -30,3 +38,19 @@ jobs:
 
       - name: Test
         run: make test
+
+  # Single stable check to require in branch protection, instead of the four
+  # brittle matrix names (which break if the matrix is renamed). `if: always()`
+  # makes this job run even when a matrix leg fails, and the explicit result
+  # check fails it — without that, a failed matrix would SKIP this job, and a
+  # skipped required check can be treated as passed, silently opening the gate.
+  ci-success:
+    needs: build-and-test
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify all matrix jobs passed
+        run: |
+          result='${{ needs.build-and-test.result }}'
+          echo "build-and-test result: $result"
+          [ "$result" = "success" ] || exit 1

.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+# Fires when a release PR (dev -> master, titled vX.Y.Z) is merged. The git
+# tag is the single source of truth: this workflow CREATES the tag from the PR
+# title, builds the optimized binary per platform with the version injected at
+# compile time (make ... RAY_VERSION=X.Y.Z), and publishes a GitHub Release.
+# No source file is bumped and nothing is pushed to the protected master branch
+# — only a tag ref and a release are created, which GITHUB_TOKEN can do without
+# any bypass token. Non-release merges to master (title not vX.Y.Z) are ignored.
+
+on:
+  pull_request:
+    branches: [master]
+    types: [closed]
+
+permissions:
+  contents: write   # create the tag + the GitHub Release
+
+jobs:
+  prepare:
+    # Only on an actual merge whose title declares a release version.
+    if: >-
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.title, 'v')
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.parse.outputs.version }}
+    steps:
+      - name: Parse version from PR title
+        id: parse
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$PR_TITLE" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "Merged PR title '$PR_TITLE' is not a release version — skipping."
+            exit 1
+          fi
+          echo "version=${BASH_REMATCH[1]}" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v4
+
+      - name: Create tag and draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ steps.parse.outputs.version }}
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+        run: |
+          set -euo pipefail
+          # Creates tag vX.Y.Z at the merge commit AND a draft release in one
+          # step. Draft so artifacts attach before the release goes public.
+          gh release create "v$VERSION" \
+            --target "$MERGE_SHA" \
+            --title "v$VERSION" \
+            --generate-notes \
+            --draft
+
+  build:
+    needs: prepare
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+          - os: macos-latest
+          # Windows is not build-ready yet (IOCP stub, unguarded POSIX in
+          # main.c/heap.c, no Makefile path). Add once the port lands:
+          # - os: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: v${{ needs.prepare.outputs.version }}
+
+      - name: Build release artifact
+        run: make dist RAY_VERSION=${{ needs.prepare.outputs.version }}
+
+      - name: Upload artifacts to release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          gh release upload "v${{ needs.prepare.outputs.version }}" \
+            dist/*.tar.gz dist/*.sha256 --clobber
+
+  publish:
+    needs: [prepare, build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Publish release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release edit "v${{ needs.prepare.outputs.version }}" --draft=false

.github/workflows/version-guard.yml

@@ -0,0 +1,58 @@
+name: Version Guard
+
+# Fast feedback on release PRs (dev -> master): the PR title must declare a
+# clean, unused, strictly-increasing semver "vX.Y.Z". The git tag is the
+# single source of truth for the version (see RELEASE.md); this check stops a
+# bad number from ever reaching release.yml. Make this a required status check
+# on master so a malformed/duplicate version can't be merged.
+
+on:
+  pull_request:
+    branches: [master]
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # need all tags for the monotonicity check
+
+      - name: Validate release version in PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+
+          # 1. Format: title must be exactly vX.Y.Z
+          if [[ ! "$PR_TITLE" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "::error::PR title must be a release version 'vX.Y.Z' (e.g. v2.1.3), got: '$PR_TITLE'"
+            exit 1
+          fi
+          version="${BASH_REMATCH[1]}"
+          echo "Release version: $version"
+
+          git fetch --tags --quiet
+
+          # 2. Tag must not already exist
+          if git rev-parse -q --verify "refs/tags/v$version" >/dev/null; then
+            echo "::error::tag v$version already exists — pick a higher version"
+            exit 1
+          fi
+
+          # 3. Must be strictly greater than the latest existing vX.Y.Z tag
+          latest="$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' | sed 's/^v//' | sort -V | tail -1)"
+          if [[ -z "$latest" ]]; then
+            echo "No prior release tag found; $version is the first release."
+            exit 0
+          fi
+          highest="$(printf '%s\n%s\n' "$latest" "$version" | sort -V | tail -1)"
+          if [[ "$highest" != "$version" || "$version" == "$latest" ]]; then
+            echo "::error::version $version must be strictly greater than the latest release $latest"
+            exit 1
+          fi
+          echo "OK: $version > $latest"

Makefile

@@ -2,16 +2,26 @@ CC      ?= clang
 STD     = c17
 AR      = ar
 TARGET  = rayforce
-# Version is authoritative in include/rayforce.h — extract it here
-VERSION_MAJOR := $(shell grep 'RAY_VERSION_MAJOR' include/rayforce.h | head -1 | awk '{print $$3}')
-VERSION_MINOR := $(shell grep 'RAY_VERSION_MINOR' include/rayforce.h | head -1 | awk '{print $$3}')
-VERSION_PATCH := $(shell grep 'RAY_VERSION_PATCH' include/rayforce.h | head -1 | awk '{print $$3}')
-VERSION       = $(VERSION_MAJOR).$(VERSION_MINOR).$(VERSION_PATCH)
+# Version: the git tag is the single source of truth. Precedence:
+#   explicit override (CI passes RAY_VERSION=X.Y.Z from the release PR title)
+#   > latest git tag (vX.Y.Z) > 0.0.0 dev default.
+# The value is injected into the build via -D below (see DEFS); nothing is
+# hand-edited in source to cut a release. See RELEASE.md.
+RAY_VERSION ?= $(shell git describe --tags --match 'v[0-9]*.[0-9]*.[0-9]*' --abbrev=0 2>/dev/null | sed 's/^v//')
+ifeq ($(strip $(RAY_VERSION)),)
+  RAY_VERSION := 0.0.0
+endif
+VERSION       = $(RAY_VERSION)
+VERSION_MAJOR := $(word 1,$(subst ., ,$(RAY_VERSION)))
+VERSION_MINOR := $(word 2,$(subst ., ,$(RAY_VERSION)))
+VERSION_PATCH := $(word 3,$(subst ., ,$(RAY_VERSION)))
 GIT_HASH := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 BUILD_DATE := $(shell date -u +%Y-%m-%d)
 
 WARNS   = -Wall -Wextra -Werror -Wstrict-prototypes -Wno-unused-parameter
-DEFS    = -DRAYFORCE_GIT_COMMIT=\"$(GIT_HASH)\" -DRAYFORCE_BUILD_DATE=\"$(BUILD_DATE)\"
+DEFS    = -DRAYFORCE_GIT_COMMIT=\"$(GIT_HASH)\" -DRAYFORCE_BUILD_DATE=\"$(BUILD_DATE)\" \
+          -DRAY_VERSION_MAJOR=$(VERSION_MAJOR) -DRAY_VERSION_MINOR=$(VERSION_MINOR) \
+          -DRAY_VERSION_PATCH=$(VERSION_PATCH) -DRAYFORCE_VERSION=\"$(RAY_VERSION)\"
 INCLUDES = -Iinclude -Isrc
 # Header-dependency tracking: -MMD emits a .d makefile fragment next to
 # each .o listing the headers it included (user headers only, not system);
@@ -101,6 +111,21 @@ lib: CFLAGS = $(RELEASE_CFLAGS)
 lib: $(LIB_OBJ)
 	$(AR) rc lib$(TARGET).a $(LIB_OBJ)
 
+# Release tarball: build the optimized binary and package it as
+# dist/rayforce-<version>-<os>-<arch>.tar.gz plus a SHA-256 checksum.
+# Used by .github/workflows/release.yml (which passes RAY_VERSION=X.Y.Z) and
+# runnable locally. VERSION comes from the tag/override resolved at the top.
+dist: release
+	@mkdir -p dist
+	@os=$$(uname -s | tr 'A-Z' 'a-z'); arch=$$(uname -m); \
+	 name=$(TARGET)-$(VERSION)-$$os-$$arch; stage=dist/$$name; \
+	 mkdir -p $$stage; \
+	 cp $(TARGET) LICENSE README.md include/rayforce.h $$stage/; \
+	 tar -czf dist/$$name.tar.gz -C dist $$name; \
+	 rm -rf $$stage; \
+	 ( cd dist && { command -v sha256sum >/dev/null 2>&1 && sha256sum $$name.tar.gz || shasum -a 256 $$name.tar.gz; } > $$name.tar.gz.sha256 ); \
+	 echo "built dist/$$name.tar.gz"
+
 # Allocator micro-benchmark (release-optimized, linked against lib objects).
 # Compile all sources fresh with RELEASE_CFLAGS so the benchmark measures
 # the release allocator, not a sanitizer-instrumented debug build.
@@ -148,14 +173,22 @@ bench-join-dup:
 		bench/join_dup/main.c $(LIB_SRC) $(LIBS) $(RELEASE_LDFLAGS)
 	./bench-join-dup
 
+# Worker threads per process during tests. Without this the runtime
+# auto-sizes to ncpu-1, so on a many-core box the in-process harness AND
+# every server it spawns via .sys.exec each create ~ncpu-1 threads — a lot of
+# wasted CPU for tiny test inputs. RAYFORCE_CORES (honored by ray_pool_create)
+# caps it; children inherit the env. Override for a fuller parallel stress,
+# e.g. `make test TEST_CORES=0` (serial) or `make test TEST_CORES=8`.
+TEST_CORES ?= 2
+
 # Tests.  Depends on $(TARGET) because test/rfl/system/ipc_diff.rfl
 # spawns ./$(TARGET) as an IPC server via .sys.exec — both binaries
 # must exist on disk and share the build flavour (sanitizers, coverage).
 test: CFLAGS = $(DEBUG_CFLAGS)
 test: LDFLAGS = $(DEBUG_LDFLAGS)
 test: $(TARGET) $(LIB_OBJ) $(TEST_OBJ)
 	$(CC) $(CFLAGS) -o $(TARGET).test $(LIB_OBJ) $(TEST_OBJ) $(LIBS) $(LDFLAGS) -Itest
-	./$(TARGET).test
+	RAYFORCE_CORES=$(TEST_CORES) ./$(TARGET).test
 
 # Coverage report.  Builds both binaries with clang source-based
 # instrumentation, runs the test suite (writing one .profraw per
@@ -194,14 +227,14 @@ clean:
 	-rm -f $(LIB_OBJ) $(MAIN_OBJ) $(TEST_OBJ)
 	-rm -f $(DEPS)
 	-rm -f $(TARGET) $(TARGET).test lib$(TARGET).a
-	-rm -rf build build_release
+	-rm -rf build build_release dist
 	# Test-generated fixtures (see test/rfl/system/*.rfl) — should not linger after a run.
 	-rm -f rf_test_*.csv
 	# Coverage artefacts (see `make coverage`).
 	-rm -f cov-*.profraw default.profraw coverage.profdata
 	-rm -rf coverage_html
 
-.PHONY: default debug release lib bench-alloc bench-join-buildside bench-join-dup test coverage clean
+.PHONY: default debug release lib dist bench-alloc bench-join-buildside bench-join-dup test coverage clean
 
 # Header dependencies last: .d fragments only add prerequisites to the
 # object targets above, and being last they can't hijack the default goal.

RELEASE.md

@@ -0,0 +1,68 @@
+# Release process
+
+Rayforce uses a tag-driven release flow. **The git tag is the single source of
+truth for the version** — no version literal is ever hand-edited in source.
+
+## Branch model
+
+- **`dev`** — integration upstream. Feature/fix branches merge here. CI runs on
+  every push and PR.
+- **`master`** — protected, stable releases only. The only way in is a merged
+  release PR.
+
+## Cutting a release
+
+1. Make sure `dev` is green and ready.
+2. Open a pull request **`dev` → `master`** with the title set to the new
+   version: **`vX.Y.Z`** (e.g. `v2.1.3`).
+   - The **Version Guard** check validates the title: it must be a clean
+     `vX.Y.Z`, must not already be tagged, and must be strictly greater than the
+     latest release.
+3. Once CI and Version Guard are green, **merge** the PR (or enable
+   auto-merge so it merges itself when checks pass).
+4. On merge, the **Release** workflow automatically:
+   - creates the tag `vX.Y.Z` at the merge commit,
+   - builds the optimized binary for Linux and macOS with the version injected
+     at compile time (`make dist RAY_VERSION=X.Y.Z`),
+   - packages `rayforce-X.Y.Z-<os>-<arch>.tar.gz` + a `.sha256` checksum,
+   - publishes a GitHub Release with auto-generated notes and the artifacts.
+
+That's the whole ritual. **Never edit the version in source to make a release** —
+the tag is authoritative.
+
+## How the version reaches the binary
+
+The Makefile resolves the version (CI override `RAY_VERSION=` > latest git tag >
+`0.0.0` dev default) and injects it at compile time via `-D`, exactly like it
+already does for the git commit and build date. `ray_version_string()`, the REPL
+banner, and `.sys.build` all report that value. The literals in
+`include/rayforce.h` are only `#ifndef`-guarded `0.0.0` fallbacks for untagged
+builds and for downstream code that includes the header without our `-D` flags.
+
+A plain local `make` on an untagged commit reports `0.0.0`; with tags present it
+reports the latest via `git describe`. To build a specific version locally:
+
+```sh
+make dist RAY_VERSION=2.1.3
+```
+
+## One-time repository setup (GitHub)
+
+- **Branch protection / ruleset on `master`**: require a pull request before
+  merging; require these two status checks to pass, and disallow direct pushes:
+  - **`ci-success`** — a single aggregator job in `ci.yml` that goes green only
+    when every CI matrix leg (ubuntu/macOS × debug/release) passed. Require this
+    one instead of the four matrix names so renaming the matrix can't silently
+    drop the gate.
+  - **`check-version`** — the Version Guard job that validates the release
+    version in the PR title.
+- No release secret or bypass token is needed — the default `GITHUB_TOKEN`
+  (`contents: write`) creates the tag and the release. The release workflow never
+  pushes a commit to `master`, only a tag ref.
+
+## Platform support
+
+Linux and macOS binaries are published today. Windows is not build-ready yet
+(IOCP backend is a stub, `main.c`/`heap.c` have unguarded POSIX calls, and the
+Makefile has no Windows toolchain path); once ported, add a `windows-latest` row
+to the `build` matrix in `.github/workflows/release.yml`.

include/rayforce.h

@@ -35,9 +35,21 @@ extern "C" {
 
 /* ===== Semantic Versioning ===== */
 
-#define RAY_VERSION_MAJOR 2
-#define RAY_VERSION_MINOR 1
+/* The real version is injected at build time via -D from the git tag (the
+ * single source of truth — see the Makefile and RELEASE.md). These are only
+ * fallbacks: 0.0.0 marks an untagged/dev build, and they give downstream code
+ * that includes this header without our -D flags a defined value. They are
+ * #ifndef-guarded so the injected -D wins without a -Wmacro-redefined error
+ * under -Werror. Do NOT hand-edit these to cut a release — tag instead. */
+#ifndef RAY_VERSION_MAJOR
+#define RAY_VERSION_MAJOR 0
+#endif
+#ifndef RAY_VERSION_MINOR
+#define RAY_VERSION_MINOR 0
+#endif
+#ifndef RAY_VERSION_PATCH
 #define RAY_VERSION_PATCH 0
+#endif
 
 /* Packed version number: 0xMMmmpp (MM=major, mm=minor, pp=patch) */
 #define RAY_VERSION_NUMBER \