[changelog] Bootstrap standalone package

.docheader

@@ -0,0 +1,13 @@
+/**
+ * Standalone changelog domain and CLI runtime for Fast Forward PHP packages.
+ *
+ * This file is part of fast-forward/changelog project.
+ *
+ * @author   Felipe Sayao Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/changelog
+ * @see      https://github.com/php-fast-forward/changelog/issues
+ * @see      https://php-fast-forward.github.io/changelog/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{yml,yaml,json,md,rst}]
+indent_size = 2
+
+[composer.json]
+indent_size = 4

.gitattributes

@@ -0,0 +1,12 @@
+*                       text=auto
+/.github/               export-ignore
+/docs/                  export-ignore
+/tests/                 export-ignore
+/.editorconfig          export-ignore
+/.gitattributes         export-ignore
+/.gitignore             export-ignore
+/.php-cs-fixer.dist.php export-ignore
+/composer-dependency-analyser.php export-ignore
+/AGENTS.md              export-ignore
+/phpunit.xml.dist       export-ignore
+/README.md              export-ignore

.gitignore

@@ -0,0 +1,10 @@
+.dev-tools/
+.idea/
+.phpunit.cache/
+.vscode/
+backup/
+tmp/
+vendor/
+*.cache
+.DS_Store
+composer.lock

AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS - Fast Forward Changelog
+
+This repository contains the standalone changelog domain and CLI runtime used
+across Fast Forward PHP packages.
+
+## Repository Surfaces
+
+- CLI entrypoint: [`bin/changelog`](bin/changelog)
+- Console wiring: [`src/Console/`](src/Console/)
+- Commands: [`src/Console/Command/`](src/Console/Command/)
+- Domain model: [`src/Document/`](src/Document/), [`src/Entry/`](src/Entry/)
+- Parsing and rendering: [`src/Parser/`](src/Parser/), [`src/Renderer/`](src/Renderer/)
+- File and Git helpers: [`src/Filesystem/`](src/Filesystem/), [`src/Git/`](src/Git/)
+- Changelog services: [`src/Manager/`](src/Manager/)
+- Tests: [`tests/`](tests/)
+- Docs: [`docs/`](docs/)
+- Release history: [`CHANGELOG.md`](CHANGELOG.md)
+
+## Setup And Local Workflow
+
+- Install dependencies with `composer install`.
+- Run focused tests with `vendor/bin/phpunit`.
+- Validate package metadata with `composer validate --strict`.
+
+## Design Notes
+
+- Keep the package free of runtime dependencies on `fast-forward/dev-tools`.
+- Keep command orchestration thin and push changelog behavior into focused services.
+- Preserve deterministic Keep a Changelog rendering so consumer workflows can rely on stable output.

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Bootstrap the standalone changelog domain, document model, manager, and reusable CLI commands (#1)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Sayao Lobato Abreu <github@mentordosnerds.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,107 @@
-# changelog
+# Fast Forward Changelog
+
 Standalone changelog domain and CLI runtime for Fast Forward PHP packages.
+
+[![PHP Version](https://img.shields.io/badge/php-%5E8.3-777BB4?logo=php&logoColor=white)](https://www.php.net/releases/)
+[![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fchangelog-F28D1A.svg?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/changelog)
+[![License](https://img.shields.io/github/license/php-fast-forward/changelog?color=64748B)](LICENSE)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/php-fast-forward?logo=githubsponsors&logoColor=white&color=EC4899)](https://github.com/sponsors/php-fast-forward)
+
+## ✨ Features
+
+- 📘 Parse and render Keep a Changelog 1.1.0 documents deterministically
+- 🛠️ Manage changelog entries and promote `Unreleased` into published releases
+- 🚀 Expose reusable Symfony Console commands for release automation
+- 🔌 Stay embeddable so larger CLIs can register the commands directly
+
+## 📦 Installation
+
+```bash
+composer require fast-forward/changelog
+```
+
+Requirements:
+
+- PHP `8.3+`
+- Symfony Console, Filesystem, and Process components
+
+## 🛠️ Usage
+
+Run the standalone CLI:
+
+```bash
+changelog list
+changelog changelog:entry "Add release automation"
+changelog changelog:resolve-version
+changelog changelog:render-release-notes 1.2.0
+```
+
+Register the commands inside another Symfony Console application:
+
+```php
+use DI\Container;
+use FastForward\Changelog\Console\Command\ChangelogEntryCommand;
+use FastForward\Changelog\Console\Command\ChangelogPromoteCommand;
+use FastForward\Changelog\Console\Command\ChangelogReleaseNotesRenderCommand;
+use FastForward\Changelog\Console\Command\ChangelogVersionResolveCommand;
+use Symfony\Component\Console\Application;
+
+$container = new Container();
+$application = new Application('My Tooling');
+
+$application->add($container->get(ChangelogEntryCommand::class));
+$application->add($container->get(ChangelogPromoteCommand::class));
+$application->add($container->get(ChangelogVersionResolveCommand::class));
+$application->add($container->get(ChangelogReleaseNotesRenderCommand::class));
+```
+
+## 🧰 API Summary
+
+| Class | Responsibility |
+|-------|----------------|
+| `ChangelogManager` | Load, mutate, promote, infer, and render changelog releases |
+| `ChangelogParser` | Parse Markdown into the managed changelog document model |
+| `MarkdownRenderer` | Render deterministic changelog Markdown and release-note bodies |
+| `ChangelogDocument` / `ChangelogRelease` | Immutable document model for release sections |
+
+## 🔌 Integration
+
+This package is designed to be shared by:
+
+- `fast-forward/dev-tools` as an aggregator of reusable CLI domains
+- `fast-forward/github-actions` as a source of changelog-aware workflow commands
+- standalone package repositories that want deterministic changelog automation
+
+## 📁 Directory Structure
+
+```text
+bin/
+docs/
+src/
+  Console/
+  Document/
+  Entry/
+  Filesystem/
+  Git/
+  Manager/
+  Parser/
+  Renderer/
+tests/
+```
+
+## 🛡 License
+
+MIT © 2026 Felipe Sayao Lobato Abreu
+
+## 🤝 Contributing
+
+Issues and pull requests are welcome. Run `composer validate --strict` and `vendor/bin/phpunit` before opening a PR.
+
+## 🔗 Links
+
+- [Repository](https://github.com/php-fast-forward/changelog)
+- [Issues](https://github.com/php-fast-forward/changelog/issues)
+- [Packagist](https://packagist.org/packages/fast-forward/changelog)
+- [Documentation](https://php-fast-forward.github.io/changelog/)
+- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+- [Semantic Versioning](https://semver.org/spec/v2.0.0.html)

bin/changelog

@@ -0,0 +1,37 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Standalone changelog domain and CLI runtime for Fast Forward PHP packages.
+ *
+ * This file is part of fast-forward/changelog project.
+ *
+ * @author   Felipe Sayao Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/changelog
+ * @see      https://github.com/php-fast-forward/changelog/issues
+ * @see      https://php-fast-forward.github.io/changelog/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+use FastForward\Changelog\Console\Changelog;
+
+$autoloadCandidates = [
+    __DIR__ . '/../vendor/autoload.php',
+    __DIR__ . '/../../../autoload.php',
+];
+
+foreach ($autoloadCandidates as $autoloadCandidate) {
+    if (is_file($autoloadCandidate)) {
+        require $autoloadCandidate;
+
+        exit((new Changelog())->run());
+    }
+}
+
+fwrite(STDERR, "Could not locate Composer autoload.php for fast-forward/changelog.\n");
+
+exit(1);

composer.json

@@ -0,0 +1,80 @@
+{
+    "name": "fast-forward/changelog",
+    "description": "Standalone changelog domain and CLI runtime for Fast Forward PHP packages.",
+    "license": "MIT",
+    "type": "library",
+    "keywords": [
+        "changelog",
+        "cli",
+        "fast-forward",
+        "keep-a-changelog",
+        "php-di",
+        "release-notes",
+        "symfony-console"
+    ],
+    "readme": "README.md",
+    "authors": [
+        {
+            "name": "Felipe Sayao Lobato Abreu",
+            "email": "github@mentordosnerds.com",
+            "homepage": "https://github.com/coisa",
+            "role": "Maintainer"
+        }
+    ],
+    "homepage": "https://github.com/php-fast-forward/changelog",
+    "support": {
+        "issues": "https://github.com/php-fast-forward/changelog/issues",
+        "wiki": "https://github.com/php-fast-forward/changelog/wiki",
+        "source": "https://github.com/php-fast-forward/changelog",
+        "docs": "https://php-fast-forward.github.io/changelog/"
+    },
+    "funding": [
+        {
+            "type": "github",
+            "url": "https://github.com/sponsors/php-fast-forward"
+        },
+        {
+            "type": "custom",
+            "url": "https://www.paypal.com/donate/?business=JLDAF45XZ8D84"
+        }
+    ],
+    "require": {
+        "php": "^8.3",
+        "php-di/php-di": "^7.0",
+        "symfony/console": "^7.4 || ^8.0",
+        "symfony/filesystem": "^7.4 || ^8.0",
+        "symfony/process": "^7.4 || ^8.0",
+        "thecodingmachine/safe": "^3.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^12.0 || ^13.0"
+    },
+    "minimum-stability": "stable",
+    "autoload": {
+        "psr-4": {
+            "FastForward\\Changelog\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "FastForward\\Changelog\\Tests\\": "tests/"
+        }
+    },
+    "bin": [
+        "bin/changelog"
+    ],
+    "config": {
+        "platform": {
+            "php": "8.3.0"
+        },
+        "sort-packages": true
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-main": "1.x-dev"
+        }
+    },
+    "scripts": {
+        "test": "phpunit"
+    }
+}

docs/index.rst

@@ -0,0 +1,28 @@
+Fast Forward Changelog
+======================
+
+``fast-forward/changelog`` provides the standalone changelog domain and CLI
+runtime used by Fast Forward PHP packages.
+
+Installation
+------------
+
+.. code-block:: bash
+
+   composer require fast-forward/changelog
+
+Standalone CLI
+--------------
+
+.. code-block:: bash
+
+   changelog changelog:entry "Add release automation"
+   changelog changelog:resolve-version
+   changelog changelog:render-release-notes 1.2.0
+
+Embedded Commands
+-----------------
+
+The package also exposes reusable Symfony Console commands so larger tooling
+applications can register them directly inside local runtimes such as
+``fast-forward/dev-tools`` and ``fast-forward/github-actions``.

phpunit.xml.dist

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         executionOrder="depends,defects"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="Fast Forward Changelog">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>