From d63de44d9e73c735fbcc5b1239f284d12debdd9f Mon Sep 17 00:00:00 2001
From: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
Date: Fri, 17 Apr 2026 03:58:40 +0000
Subject: [PATCH] build(fix): add RELEASES.md and fix existing docs to reflect reality

---
 RELEASES.md     |  101 +++++++++++++++++++++++++++++++++
 CONTRIBUTING.md |   16 +++++
 .release-it.ts  |   50 ++++++++++++++++
 README.md       |    8 --
 4 files changed, 166 insertions(+), 9 deletions(-)

diff --git a/.release-it.ts b/.release-it.ts
index d01c64e..5747389 100644
--- a/.release-it.ts
+++ b/.release-it.ts
@@ -1,11 +1,59 @@
+import { execSync } from "node:child_process";
 import type { Config } from "release-it";
 
+interface ConventionalCommitLike {
+	type?: string;
+	notes?: unknown[];
+}
+
+function getCurrentBranch(): string {
+	try {
+		return execSync("git rev-parse --abbrev-ref HEAD", {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+		}).trim();
+	} catch (error: unknown) {
+		console.error("Failed to determine the current Git branch.");
+		console.error(error);
+		process.exit(1);
+	}
+}
+
+function isPreReleaseRun(argv: string[]): boolean {
+	return argv.some((argument) => {
+		return (
+			argument === "--preRelease" ||
+			argument.startsWith("--preRelease=") ||
+			argument === "--preReleaseId" ||
+			argument.startsWith("--preReleaseId=")
+		);
+	});
+}
+
+const currentBranch = getCurrentBranch();
+const preReleaseRun = isPreReleaseRun(process.argv);
+
+if (preReleaseRun && currentBranch !== "development") {
+	console.error(
+		`Pre-releases are only allowed on "development". Current branch: "${currentBranch}".`,
+	);
+	process.exit(1);
+}
+
+if (!preReleaseRun && currentBranch !== "main") {
+	console.error(
+		`Stable releases are only allowed on "main". Current branch: "${currentBranch}".`,
+	);
+	process.exit(1);
+}
+
 const config = {
 	npm: {
 		publish: false,
 	},
 	git: {
 		requireCleanWorkingDir: true,
+		requireBranch: currentBranch,
 		commit: true,
 		commitMessage: "chore(release): v${version}",
 		commitArgs: ["--no-verify"],
@@ -41,7 +89,7 @@
 					{ type: "ai", section: "AI Instruction Files" },
 				],
 			},
-			whatBump(commits: Array<{ type?: string; notes?: unknown[] }>) {
+			whatBump(commits: ConventionalCommitLike[]) {
 				let level: 2 | 1 | 0 | null = null;
 
 				for (const commit of commits) {
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 39898f3..00605d9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,16 @@
 
 Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository.
 
+* [Ways to Contribute](#ways-to-contribute)
+* [Release Process](#release-process)
+* [Before You Start](#before-you-start)
+* [Reporting Bugs and Requesting Features](#reporting-bugs-and-requesting-features)
+* [Pull Request Workflow](#pull-request-workflow)
+* [Circumventing Git Hooks](#circumventing-git-hooks)
+* [Documentation Contributions](#documentation-contributions)
+* [Attribution](#attribution)
+* [License](#license)
+
 ## Ways to Contribute
 
 * Report bugs
@@ -10,6 +20,12 @@
 * Improve templates, styles, or assets
 * Improve translations in `i18n/*.toml`
 
+## Release Process
+
+The project follows a structured release workflow based on conventional commits, staging branches, and automated versioning.
+
+For details, see [RELEASES.md](./RELEASES.md).
+
 ## Before You Start
 
 1. Use a compatible Hugo version (see [`config/_default/module.toml`](https://github.com/theNewDynamic/gohugo-theme-ananke/blob/main/config/_default/module.toml) for the current state).
diff --git a/README.md b/README.md
index 244f3d4..a7032ed 100644
--- a/README.md
+++ b/README.md
@@ -19,14 +19,6 @@
 * Reading time/word count support
 * Robots.txt handling by environment
 
-## Compatibility
-
-> [!IMPORTANT]
-> The `main` branch is maintained for Hugo **v0.146.0+**.
->
-> * For Hugo **v0.128.1 to v0.145.0**, use branch [`release/v2.12`](https://github.com/theNewDynamic/gohugo-theme-ananke/tree/release/v2.12).
-> * For older Hugo versions, use a matching tag from the [releases page](https://github.com/theNewDynamic/gohugo-theme-ananke/tags).
-
 ## Installation
 
 Ananke supports both installation methods:
diff --git a/RELEASES.md b/RELEASES.md
new file mode 100644
index 0000000..a1d34f3
--- /dev/null
+++ b/RELEASES.md
@@ -0,0 +1,101 @@
+# Release Policy
+
+This document defines the release workflow for Ananke.
+
+The project follows a structured branching and release strategy based on conventional commits and automated versioning.
+
+## Overview
+
+* `main` is the stable production branch
+* `development` is the staging branch
+* feature work happens in dedicated branches
+* releases and pre-releases are automated via npm scripts
+
+## Versioning
+
+* Version numbers are determined automatically using **conventional commits**
+* Do not manually set version numbers
+* Commit messages must follow the conventional commits specification
+
+Examples:
+
+* `feat: add new layout option`
+* `fix: correct mobile navigation`
+* `docs: update configuration guide`
+
+## Branching Model
+
+### main
+
+* Contains only stable, released code
+* Updated **only via rebase from `development`**
+* Tagged for official releases
+
+### development
+
+* Acts as staging environment
+* Receives all feature and fix changes
+* Used for testing before release
+* Hosts pre-releases
+
+### feature branches
+
+* All work must happen in dedicated branches
+* Branch from `development`
+* Naming is flexible but should be descriptive
+
+Examples:
+
+* `feature/header-redesign`
+* `fix/mobile-menu`
+* `docs/improve-installation`
+
+## Pull Request Workflow
+
+* All pull requests must target `development`
+* No direct commits to `main` or `development`
+
+### Merging rules
+
+* Feature branches → `development`: **squash merge**
+* `development` → `main`: **rebase**
+
+This ensures:
+
+* clean history in `main`
+* meaningful commit grouping in `development`
+
+## Release Types
+
+### Pre-releases
+
+Used for testing and validation.
+
+```bash
+npm run release:pre
+```
+
+* Created from `development`
+* Marked as pre-release
+* Used for validation before stable release
+
+### Stable releases
+
+```bash
+npm run release
+```
+
+* Created from `main`
+* Tagged as official release
+* Represents stable production state
+
+## Release Flow
+
+Typical flow:
+
+1. Create feature branch from `development`
+2. Open PR → merge (squash) into `development`
+3. Test changes on `development`
+4. Create pre-release if needed
+5. Rebase `development` → `main`
+6. Run stable release on `main`

--
Gitblit v1.10.0