build(fix): add RELEASES.md and fix existing docs to reflect reality

Patrick Kollitsch

17.58.2026 d63de44d9e73c735fbcc5b1239f284d12debdd9f

build(fix): add RELEASES.md and fix existing docs to reflect reality

 .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) {

 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).

 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:

 RELEASES.md

New file
@@ -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`