@ferrflow/doc 7.17.0

package/docs-v0/configuration/config-file.md

@@ -0,0 +1,97 @@
+---
+title: ferrflow.toml
+description: Complete reference for the ferrflow.toml configuration file.
+slug: v0/docs/configuration/config-file
+---
+
+FerrFlow reads `ferrflow.toml` from the root of your repository. If no config file is found, it auto-detects common version files in the current directory.
+
+## `[workspace]`
+
+Global settings that apply to all packages.
+
+```toml
+[workspace]
+remote = "origin"   # Git remote to push to (default: "origin")
+branch = "main"     # Branch to push to (default: auto-detected from remote HEAD)
+```
+
+## `[[package]]`
+
+Defines a package to version. You can have one or many.
+
+```toml
+[[package]]
+name      = "api"                        # Used in git tags: api@v1.2.0
+path      = "packages/api"               # Path to the package root
+changelog = "packages/api/CHANGELOG.md"  # Where to write the changelog
+shared_paths = ["packages/shared/"]      # Changes here also trigger this package
+```
+
+| Field          | Required | Description                                                    |
+| -------------- | -------- | -------------------------------------------------------------- |
+| `name`         | yes      | Package identifier, used in git tag prefix                     |
+| `path`         | yes      | Relative path to the package directory                         |
+| `changelog`    | no       | Path to the changelog file (defaults to `{path}/CHANGELOG.md`) |
+| `shared_paths` | no       | List of paths — changes in any of them trigger this package    |
+
+## `[[package.versioned_files]]`
+
+Files where the version number should be updated.
+
+```toml
+[[package.versioned_files]]
+path   = "packages/api/Cargo.toml"
+format = "toml"
+```
+
+| `format` | File                               | Field updated                                     |
+| -------- | ---------------------------------- | ------------------------------------------------- |
+| `toml`   | `Cargo.toml`, `pyproject.toml`     | `[package].version`                               |
+| `json`   | `package.json`                     | `version`                                         |
+| `xml`    | `pom.xml`                          | First `<version>` element                         |
+| `gradle` | `build.gradle`, `build.gradle.kts` | `version = "..."`                                 |
+| `gomod`  | `go.mod`                           | No file update — version comes from git tags only |
+
+A package can have multiple versioned files:
+
+```toml
+[[package.versioned_files]]
+path   = "Cargo.toml"
+format = "toml"
+
+[[package.versioned_files]]
+path   = "npm/package.json"
+format = "json"
+```
+
+## Complete example
+
+```toml
+[workspace]
+remote = "origin"
+branch = "main"
+
+[[package]]
+name      = "api"
+path      = "packages/api"
+changelog = "packages/api/CHANGELOG.md"
+shared_paths = ["packages/shared/"]
+
+[[package.versioned_files]]
+path   = "packages/api/Cargo.toml"
+format = "toml"
+
+[[package]]
+name      = "site"
+path      = "packages/site"
+changelog = "packages/site/CHANGELOG.md"
+shared_paths = ["packages/shared/"]
+
+[[package.versioned_files]]
+path   = "packages/site/package.json"
+format = "json"
+```
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Run <code>ferrflow init</code> to generate this file automatically based on what FerrFlow detects in your repo.</p>
+</div></aside>

package/docs-v0/configuration/formats.md

@@ -0,0 +1,86 @@
+---
+title: Supported formats
+description: Version file formats that FerrFlow can read and update.
+slug: v0/docs/configuration/formats
+---
+
+## TOML
+
+Used by Rust (`Cargo.toml`) and Python (`pyproject.toml`).
+
+FerrFlow updates the `version` field under `[package]`, `[project]`, or `[tool.poetry]`.
+
+```toml
+[package]
+name = "my-crate"
+version = "1.2.3"   # ← updated
+```
+
+## JSON
+
+Used by Node.js (`package.json`).
+
+FerrFlow updates the top-level `version` field.
+
+```json
+{
+  "name": "my-package",
+  "version": "1.2.3"
+}
+```
+
+## XML
+
+Used by Java/Maven (`pom.xml`).
+
+FerrFlow updates the first `<version>` element it encounters.
+
+```xml
+<project>
+  <groupId>com.example</groupId>
+  <artifactId>my-app</artifactId>
+  <version>1.2.3</version>   <!-- updated -->
+</project>
+```
+
+## Gradle
+
+Used by Java/Kotlin Gradle projects (`build.gradle`, `build.gradle.kts`).
+
+FerrFlow updates the `version = "..."` assignment.
+
+```groovy
+version = "1.2.3"   // updated
+```
+
+## Plain text
+
+Used for simple version files (`VERSION`, `VERSION.txt`).
+
+FerrFlow replaces the entire file content with the version number.
+
+```
+1.2.3
+```
+
+## Go modules
+
+Used by Go projects (`go.mod`).
+
+Go modules use git tags directly — FerrFlow does **not** modify `go.mod`. The version is derived entirely from the git tag (`v1.2.3` or `{name}@v1.2.3`).
+
+## Multiple files per package
+
+A package can have as many `[[package.versioned_files]]` entries as needed:
+
+```toml
+[[package.versioned_files]]
+path   = "Cargo.toml"
+format = "toml"
+
+[[package.versioned_files]]
+path   = "npm/package.json"
+format = "json"
+```
+
+Both files will be updated to the same version before the git commit.

package/docs-v0/configuration/monorepo.md

@@ -0,0 +1,59 @@
+---
+title: Monorepo
+description: Version multiple packages independently in a single repository.
+slug: v0/docs/configuration/monorepo
+---
+
+FerrFlow treats a repository as a monorepo when `ferrflow.toml` defines more than one `[[package]]`. Each package is versioned independently based on its own git history.
+
+## Package isolation
+
+FerrFlow uses path prefixes to determine which commits belong to which package. Only commits that touch files under `path` (or `shared_paths`) trigger a release for that package.
+
+```toml
+[[package]]
+name = "api"
+path = "packages/api"      # only commits touching packages/api/ trigger api releases
+
+[[package]]
+name = "site"
+path = "packages/site"     # only commits touching packages/site/ trigger site releases
+```
+
+## Shared dependencies
+
+If you have code shared between packages (e.g., a `packages/shared/` library), you can declare it as a `shared_paths` entry. A change to any shared path triggers a release for every package that lists it:
+
+```toml
+[[package]]
+name = "api"
+path = "packages/api"
+shared_paths = ["packages/shared/"]   # changing shared/ also releases api
+
+[[package]]
+name = "site"
+path = "packages/site"
+shared_paths = ["packages/shared/"]   # and also releases site
+```
+
+## Git tag format
+
+Each package gets its own tag namespace: `{name}@v{version}`.
+
+```
+api@v1.2.0
+site@v0.4.1
+```
+
+FerrFlow looks for the most recent tag matching `{name}@v*` to determine what commits are new.
+
+## Independent cadences
+
+Packages release independently. In a single `ferrflow release` run:
+
+- `api` may bump from `1.2.0` → `1.3.0` (new `feat:` commit)
+- `site` may bump from `0.4.0` → `0.4.1` (only `fix:` commits)
+- `shared` may not release at all (only `chore:` commits)
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Use <code>ferrflow check</code> to preview exactly which packages would be released and at what version before committing to a release.</p>
+</div></aside>

package/docs-v0/installation.md

@@ -0,0 +1,48 @@
+---
+title: Installation
+description: How to install FerrFlow locally or in CI.
+slug: v0/docs/installation
+---
+
+## Local installation
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="Cargo"><p class="ferr-tab__label">Cargo</p><div class="ferr-tab__body"><pre><code class="language-bash">cargo install ferrflow
+</code></pre>
+</div></div>
+
+  <div class="ferr-tab" data-label="npm"><p class="ferr-tab__label">npm</p><div class="ferr-tab__body"><pre><code class="language-bash">npm install -g ferrflow
+# or as a dev dependency
+npm install -D ferrflow
+</code></pre>
+</div></div>
+
+  <div class="ferr-tab" data-label="Binary"><p class="ferr-tab__label">Binary</p><div class="ferr-tab__body"><p>Download a pre-built binary from <a href="https://github.com/FerrLabs/FerrFlow/releases/latest">Releases</a>:</p>
+<pre><code class="language-bash"># Linux x86_64
+curl -L https://github.com/FerrLabs/FerrFlow/releases/latest/download/ferrflow-x86_64-unknown-linux-gnu.tar.gz | tar xz
+sudo mv ferrflow /usr/local/bin/
+</code></pre>
+</div></div>
+
+  <div class="ferr-tab" data-label="Docker"><p class="ferr-tab__label">Docker</p><div class="ferr-tab__body"><pre><code class="language-bash">docker run --rm -v $(pwd):/repo ghcr.io/ferrlabs/ferrflow:latest check
+</code></pre>
+</div></div>
+</div>
+
+## CI installation
+
+The recommended way to use FerrFlow in CI is the GitHub Action — no installation step needed:
+
+```yaml
+- uses: FerrLabs/ferrflow@v0
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+See [GitHub Actions](/v0/docs/ci/github-actions) and [GitLab CI](/v0/docs/ci/gitlab-ci) for complete examples.
+
+## Verify
+
+```bash
+ferrflow --version
+```

package/docs-v0/introduction.md

@@ -0,0 +1,34 @@
+---
+title: Introduction
+description: What FerrFlow is and why it exists.
+slug: v0/docs/introduction
+---
+
+FerrFlow is a single binary that automates semantic versioning for any repository — monorepo or classic, any language.
+
+It reads your commit history, determines the right version bump, updates your version files, writes a changelog, creates a git tag, and publishes a release. Zero runtime dependencies.
+
+## Why not semantic-release or changesets?
+
+Most versioning tools are coupled to a specific ecosystem or require Node.js to be present in your CI.
+
+| Tool             | Monorepo    | Multi-language | Runtime  |
+| ---------------- | ----------- | -------------- | -------- |
+| semantic-release | via plugins | JS/Node only   | Node.js  |
+| changesets       | manual bump | JS only        | Node.js  |
+| release-please   | limited     | partial        | Node.js  |
+| cargo-release    | no          | Rust only      | Rust     |
+| **FerrFlow**     | **native**  | **any**        | **none** |
+
+FerrFlow ships as a compiled binary. Drop it in any CI environment without installing a runtime.
+
+## How it works
+
+1. **Reads commits** since the last git tag for each package
+2. **Determines the bump** from [Conventional Commits](/v0/docs/reference/conventional-commits) (`feat` → minor, `fix` → patch, breaking → major)
+3. **Updates version files** — `Cargo.toml`, `package.json`, `pom.xml`, etc.
+4. **Writes the changelog** in Keep a Changelog format
+5. **Creates a git tag** (`api@v1.2.0`) and pushes
+6. **Publishes a GitHub/GitLab release** with the changelog as release notes
+
+In a monorepo, FerrFlow only releases packages that have changed, and understands shared dependency paths.

package/docs-v0/legal/telemetry.md

@@ -0,0 +1,63 @@
+---
+title: Telemetry
+description: What FerrFlow collects, how data is anonymized, and how to opt out.
+---
+
+FerrFlow collects anonymous usage telemetry to help improve the tool. This page explains exactly what is sent, how it is anonymized, and how to disable it.
+
+## What is collected
+
+Each time you run a command, FerrFlow may send a single event containing:
+
+| Field           | Description                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `event_type`    | The action performed: `check`, `release`, `version_bump`, or `init` |
+| `commits_count` | Number of commits since the last release                            |
+| `repo_hash`     | A SHA-256 hash of your git remote URL (see below)                   |
+
+Only fields relevant to the command are included. Empty fields are omitted.
+
+## How data is anonymized
+
+Your repository URL is **never sent in plain text**. FerrFlow computes a SHA-256 hash of the git remote URL and sends only the resulting hex digest. This lets us count unique repositories without knowing which repositories they are.
+
+No source code, file names, commit messages, branch names, package names, version numbers, IP addresses, or personal information are ever collected or stored.
+
+## Where data is sent
+
+Events are sent as a POST request to `https://api.ferrflow.com/events`. The request is asynchronous and non-blocking — it never slows down your workflow. If the request fails, it is silently discarded.
+
+## How to opt out
+
+You can disable telemetry entirely using either an environment variable or your config file.
+
+### Environment variable
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="Linux / macOS"><p class="ferr-tab__label">Linux / macOS</p><div class="ferr-tab__body"><pre><code class="language-bash">export FERRFLOW_TELEMETRY=false
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="Windows"><p class="ferr-tab__label">Windows</p><div class="ferr-tab__body"><pre><code class="language-powershell">$env:FERRFLOW_TELEMETRY = &quot;false&quot;
+</code></pre>
+</div></div>
+</div>
+
+Accepted values to disable: `false`, `0`, `off`, `no` (case-insensitive).
+
+### Config file
+
+<div class="ferr-tabs">
+  <div class="ferr-tab" data-label="JSON"><p class="ferr-tab__label">JSON</p><div class="ferr-tab__body"><pre><code class="language-json">{
+  &quot;workspace&quot;: {
+    &quot;telemetry&quot;: false
+  }
+}
+</code></pre>
+</div></div>
+  <div class="ferr-tab" data-label="TOML"><p class="ferr-tab__label">TOML</p><div class="ferr-tab__body"><pre><code class="language-toml">[workspace]
+telemetry = false
+</code></pre>
+</div></div>
+</div>
+
+Either method is sufficient to disable telemetry. If the config file disables it, the environment variable cannot re-enable it, and vice versa.

package/docs-v0/quickstart.md

@@ -0,0 +1,58 @@
+---
+title: Quick start
+description: Go from zero to your first automated release in under 5 minutes.
+slug: v0/docs/quickstart
+---
+
+<ol>
+<li><p><strong>Scaffold the config</strong></p>
+<p>Run <code>ferrflow init</code> at the root of your repository. It detects your version files and writes a <code>ferrflow.toml</code>:</p>
+<pre><code class="language-bash">ferrflow init
+</code></pre>
+<p>For a Rust project this produces:</p>
+<pre><code class="language-toml">[workspace]
+remote = &quot;origin&quot;
+branch = &quot;main&quot;
+
+[[package]]
+name = &quot;my-app&quot;
+path = &quot;.&quot;
+changelog = &quot;CHANGELOG.md&quot;
+
+[[package.versioned_files]]
+path = &quot;Cargo.toml&quot;
+format = &quot;toml&quot;
+</code></pre>
+</li>
+<li><p><strong>Preview what would happen</strong></p>
+<p>Before touching anything, run a dry-run to see what FerrFlow would do:</p>
+<pre><code class="language-bash">ferrflow check
+</code></pre>
+<p>Output:</p>
+<pre><code>Scanning . ...
+→ feat: add user authentication
+→ fix: correct pagination offset
+
+Bump my-app 0.1.0 → 0.2.0
+Tag my-app@v0.2.0
+</code></pre>
+</li>
+<li><p><strong>Run the release</strong></p>
+<pre><code class="language-bash">ferrflow release
+</code></pre>
+<p>FerrFlow will:</p>
+<ul>
+<li>Update <code>Cargo.toml</code> to <code>0.2.0</code></li>
+<li>Append to <code>CHANGELOG.md</code></li>
+<li>Commit the changes</li>
+<li>Create and push <code>my-app@v0.2.0</code></li>
+<li>Create a GitHub release (if <code>GITHUB_TOKEN</code> is set)</li>
+</ul>
+</li>
+</ol>
+
+## Next steps
+
+- Set up [GitHub Actions](/v0/docs/ci/github-actions) to run releases automatically on push to `main`
+- Configure a [monorepo](/v0/docs/configuration/monorepo) if you have multiple packages
+- Review the full [config reference](/v0/docs/configuration/config-file)

package/docs-v0/reference/cli.md

@@ -0,0 +1,95 @@
+---
+title: CLI commands
+description: Full reference for all FerrFlow CLI commands and flags.
+slug: v0/docs/reference/cli
+---
+
+## `ferrflow release`
+
+Run the full release pipeline: bump versions, update changelogs, commit, tag, push, and create a release.
+
+```bash
+ferrflow release [OPTIONS]
+```
+
+| Flag              | Description                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| `--dry-run`       | Preview all changes without writing, committing, or pushing |
+| `--verbose`, `-v` | Show detailed output including commit hashes and file diffs |
+
+**What it does:**
+
+1. Scans commits since the last tag for each package
+2. Determines the version bump from Conventional Commits
+3. Updates all `versioned_files` with the new version
+4. Appends the new section to `CHANGELOG.md`
+5. Creates a git commit with the version bump changes
+6. Creates and pushes the git tag (`{name}@v{version}`)
+7. Creates a GitHub/GitLab release with the changelog as notes
+
+---
+
+## `ferrflow check`
+
+Preview what `ferrflow release` would do without making any changes. Equivalent to `ferrflow release --dry-run`.
+
+```bash
+ferrflow check
+```
+
+---
+
+## `ferrflow changelog`
+
+Generate or update `CHANGELOG.md` only, without bumping versions or creating tags.
+
+```bash
+ferrflow changelog [OPTIONS]
+```
+
+| Flag        | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `--dry-run` | Print the changelog entry without writing to disk |
+
+---
+
+## `ferrflow init`
+
+Scaffold a `ferrflow.toml` config file for the current repository. Detects existing version files (`Cargo.toml`, `package.json`, etc.) and generates the appropriate config.
+
+```bash
+ferrflow init
+```
+
+---
+
+## `ferrflow status`
+
+Show the current version of each package and whether a release would be triggered.
+
+```bash
+ferrflow status [OPTIONS]
+```
+
+| Flag     | Description                         |
+| -------- | ----------------------------------- |
+| `--json` | Output in JSON format for scripting |
+
+Example output:
+
+```
+api    1.2.3   minor bump pending (1 feat commit)
+site   0.4.1   no release (only chore commits)
+```
+
+---
+
+## Global flags
+
+These flags work with all commands:
+
+| Flag              | Description                                             |
+| ----------------- | ------------------------------------------------------- |
+| `--config <PATH>` | Path to a custom config file (default: `ferrflow.toml`) |
+| `--version`       | Print the FerrFlow version and exit                     |
+| `--help`, `-h`    | Print help                                              |

package/docs-v0/reference/conventional-commits.md

@@ -0,0 +1,68 @@
+---
+title: Conventional Commits
+description: How FerrFlow interprets commit messages to determine version bumps.
+slug: v0/docs/reference/conventional-commits
+---
+
+FerrFlow follows the [Conventional Commits](https://www.conventionalcommits.org/) specification to determine how much to bump the version.
+
+## Bump rules
+
+| Commit type                   | Version bump | Example                             |
+| ----------------------------- | ------------ | ----------------------------------- |
+| `feat:`                       | **minor**    | `feat: add wallet subscriptions`    |
+| `fix:`                        | patch        | `fix: correct pagination offset`    |
+| `perf:`                       | patch        | `perf: cache user queries`          |
+| `refactor:`                   | patch        | `refactor: extract auth middleware` |
+| `feat!:` or `BREAKING CHANGE` | **major**    | `feat!: remove deprecated endpoint` |
+| `chore:`                      | none         | `chore: update dependencies`        |
+| `docs:`                       | none         | `docs: update README`               |
+| `ci:`                         | none         | `ci: add linting step`              |
+| `style:`                      | none         | `style: format code`                |
+| `test:`                       | none         | `test: add unit tests`              |
+
+## Breaking changes
+
+A breaking change can be indicated in two ways:
+
+**Exclamation mark suffix:**
+
+```
+feat!: remove the /v1/users endpoint
+fix!: change authentication header format
+```
+
+**`BREAKING CHANGE` footer:**
+
+```
+feat: redesign the API
+
+BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.
+```
+
+Both produce a **major** version bump.
+
+## Scope
+
+Scopes are optional and ignored for bump calculation. They're useful for readability:
+
+```
+feat(auth): add OAuth2 support       → minor bump
+fix(db): correct index on user table  → patch bump
+```
+
+## No release
+
+Commits with types `chore`, `docs`, `ci`, `style`, or `test` do not trigger a release. If all commits since the last tag are of these types, FerrFlow exits without creating a new version.
+
+## Multiple commits
+
+When multiple commits are present since the last tag, FerrFlow takes the **highest** bump across all of them:
+
+```
+fix: correct typo       → patch
+feat: add export button → minor   ← wins
+chore: lint             → none
+```
+
+Result: **minor** bump.

package/docs-v1/ci/github-actions.md

@@ -0,0 +1,76 @@
+---
+title: GitHub Actions
+description: Run FerrFlow releases automatically in GitHub Actions.
+---
+
+## Using the official action
+
+The easiest way to use FerrFlow in GitHub Actions is the `FerrLabs/ferrflow@v1` action. It installs the binary and runs `ferrflow release` automatically.
+
+```yaml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # required to push tags and create releases
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # full history needed for commit scanning
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+<aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p><code>fetch-depth: 0</code> is required. Without it, FerrFlow cannot find previous tags and will treat every commit as new.</p>
+</div></aside>
+
+## Permissions
+
+FerrFlow needs `contents: write` to:
+
+- Push version bump commits
+- Create and push git tags
+- Create GitHub Releases
+
+If your repository has branch protection rules, create a dedicated token with the necessary permissions and pass it as `FERRFLOW_TOKEN` or configure the action's `token` input.
+
+## Accessing the release output
+
+The action exposes the new version as an output you can use in downstream steps:
+
+```yaml
+- uses: FerrLabs/ferrflow@v1
+  id: ferrflow
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Build Docker image
+  if: steps.ferrflow.outputs.version != ''
+  run: |
+    docker build -t myimage:${{ steps.ferrflow.outputs.version }} .
+    docker push myimage:${{ steps.ferrflow.outputs.version }}
+```
+
+## Skip CI on release commits
+
+FerrFlow commits version bumps with `[skip ci]` in the message by default to prevent infinite loops. No extra configuration needed.
+
+## Monorepo example
+
+In a monorepo, FerrFlow releases each changed package in a single run:
+
+```yaml
+- uses: FerrLabs/ferrflow@v1
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# Creates api@v1.3.0 and site@v0.5.1 in one step if both changed
+```