@ferrflow/doc 7.17.0

package/docs-v4/legal/telemetry.md

@@ -0,0 +1,65 @@
+---
+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_ANONYMOUS_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_ANONYMOUS_TELEMETRY = &quot;false&quot;
+</code></pre>
+</div></div>
+</div>
+
+Accepted values to disable: `false`, `0`, `off`, `no` (case-insensitive).
+
+Since v4.10, FerrFlow also honors the standard [`DO_NOT_TRACK`](https://consoledonottrack.com/) environment variable — `DO_NOT_TRACK=1` disables telemetry without any FerrFlow-specific configuration. `FERRFLOW_TELEMETRY=false` is kept as a fallback for backwards compatibility with v0/v1 configs.
+
+### 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-v4/quickstart.md

@@ -0,0 +1,66 @@
+---
+title: Quick start
+description: Go from zero to your first automated release in under 5 minutes.
+---
+
+<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</code> config:</p>
+<pre><code class="language-bash">ferrflow init
+</code></pre>
+<p>For a Rust project this produces:</p>
+<pre><code class="language-json">{
+  &quot;$schema&quot;: &quot;https://ferrflow.com/schema/ferrflow.json&quot;,
+  &quot;workspace&quot;: {
+    &quot;tagTemplate&quot;: &quot;v{version}&quot;
+  },
+  &quot;package&quot;: [
+    {
+      &quot;name&quot;: &quot;my-app&quot;,
+      &quot;path&quot;: &quot;.&quot;,
+      &quot;changelog&quot;: &quot;CHANGELOG.md&quot;,
+      &quot;versionedFiles&quot;: [
+        { &quot;path&quot;: &quot;Cargo.toml&quot;, &quot;format&quot;: &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 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>v0.2.0</code></li>
+<li>Create a GitHub release (if <code>GITHUB_TOKEN</code> is set)</li>
+</ul>
+</li>
+</ol>
+
+<aside class="ferr-aside ferr-aside--tip"><p class="ferr-aside__title">Starting from scratch</p><div class="ferr-aside__body"><p>No prior tag? FerrFlow v3 bootstraps from the strategy&#39;s zero value automatically — the first <code>feat:</code> lands at <code>0.1.0</code>, the first <code>fix:</code> at <code>0.0.1</code>. You don&#39;t need to create a <code>v0.0.0</code> tag by hand. See <a href="/docs/reference/cli#which-version-is-bumped-from">how the baseline is chosen</a>.</p>
+</div></aside>
+
+## Next steps
+
+- Set up [GitHub Actions](/docs/ci/github-actions) to run releases automatically on push to `main`
+- Configure a [monorepo](/docs/configuration/monorepo) if you have multiple packages
+- Add [pre/post-release hooks](/docs/configuration/config-file#hooks) for custom scripts during the release lifecycle
+- Use `ferrflow version` and `ferrflow tag` in CI scripts — see the [CLI reference](/docs/reference/cli)
+- Review the full [config reference](/docs/configuration/config-file)

package/docs-v4/reference/cli.md

@@ -0,0 +1,161 @@
+---
+title: CLI commands
+description: Full reference for all FerrFlow CLI commands and flags.
+---
+
+## `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                                                      |
+| `--force`                   | Allow floating tags to move backward to a lower version                                                          |
+| `--force-version <VERSION>` | Force a specific version, skipping commit analysis. Format: `VERSION` (single repo) or `NAME@VERSION` (monorepo) |
+| `--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 `versionedFiles` with the new version
+4. Appends the new section to `CHANGELOG.md`
+5. Creates a git commit, opens a PR, or skips (depending on `releaseCommitMode`)
+6. Creates and pushes the git tag
+7. Creates a GitHub/GitLab release with the changelog as notes
+
+### Which version is bumped from
+
+Starting with FerrFlow **v3**, the baseline for every bump is **the highest semver-valid tag** for the package (e.g. `my-pkg@v2.4.1` or `v2.4.1`), not the value in the versioned file.
+
+The versioned file stays the canonical write target so downstream consumers (`cargo publish`, Docker builds, etc.) always see a coherent version, but it is no longer the source of truth for the bump computation. This prevents two classes of silent failure:
+
+- **Parallel release workflows**: two pull requests merging back-to-back used to spawn two release jobs that both read the pre-release version from the file. Both computed the same next version — the second push either collided or was silently skipped. Today the second workflow sees the first workflow's freshly-pushed tag and computes the correct next version on top of it.
+- **File/tag drift**: a revert, a merge from an old branch, or a manual edit could leave the file behind the tags. Bumping from a stale file produced tags that collided with history and the release got silently skipped with `tag X already exists, skipping`. The tag now wins; the file only wins when it is genuinely ahead (human pre-bump).
+
+Resolution order, per package:
+
+| Tag     | File    | Baseline used                  |
+| ------- | ------- | ------------------------------ |
+| present | present | `max(tag, file)` by semver     |
+| present | absent  | tag                            |
+| absent  | present | file                           |
+| absent  | absent  | strategy bootstrap (see below) |
+
+### First release on a brand-new repo
+
+When no tag exists yet _and_ the format has no version to read (notably `go.mod`, which stores the version in tags alone), FerrFlow bootstraps from the versioning strategy's zero value:
+
+| Strategy                 | Bootstrap baseline                       |
+| ------------------------ | ---------------------------------------- |
+| `semver`, `zerover`      | `0.0.0`                                  |
+| `sequential`             | `0`                                      |
+| `calver-seq`             | `0.0`                                    |
+| `calver`, `calver-short` | ignored — bump derives from today's date |
+
+From there the first `feat:` commit bumps to `0.1.0` / `1` / today's date / … and the release flow creates the tag itself — no `git tag foo@v0.0.0` ceremony required before the first run.
+
+---
+
+## `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 config file for the current repository. Detects existing version files (`Cargo.toml`, `package.json`, etc.) and generates the appropriate config.
+
+```bash
+ferrflow init [OPTIONS]
+```
+
+| Flag                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `--format <FORMAT>` | Config file format: `json`, `json5`, or `toml` |
+
+---
+
+## `ferrflow status`
+
+Show the current version of each package and whether a release would be triggered.
+
+```bash
+ferrflow status [OPTIONS]
+```
+
+| Flag                | Description                               |
+| ------------------- | ----------------------------------------- |
+| `--output <FORMAT>` | Output format: `text` (default) or `json` |
+
+Example output:
+
+```
+api    1.2.3   minor bump pending (1 feat commit)
+site   0.4.1   no release (only chore commits)
+```
+
+---
+
+## `ferrflow version`
+
+Print the current version of one or all packages. Useful in CI scripts.
+
+```bash
+ferrflow version [PACKAGE] [OPTIONS]
+```
+
+| Flag     | Description    |
+| -------- | -------------- |
+| `--json` | Output as JSON |
+
+Returns the version from the latest git tag matching the package's tag template.
+
+---
+
+## `ferrflow tag`
+
+Print the latest tag for one or all packages.
+
+```bash
+ferrflow tag [PACKAGE] [OPTIONS]
+```
+
+| Flag     | Description    |
+| -------- | -------------- |
+| `--json` | Output as JSON |
+
+---
+
+## Global flags
+
+These flags work with all commands:
+
+| Flag              | Description                                                                                         |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `--config <PATH>` | Path to a custom config file (default: auto-detected). Also accepts `FERRFLOW_CONFIG` env variable. |
+| `--version`       | Print the FerrFlow version and exit                                                                 |
+| `--help`, `-h`    | Print help                                                                                          |

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

@@ -0,0 +1,67 @@
+---
+title: Conventional Commits
+description: How FerrFlow interprets commit messages to determine version bumps.
+---
+
+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.