laravel-release-changelog-generator: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Commands

composer test              # Run Pest tests
composer test-coverage     # Run tests with coverage report
composer analyse           # PHPStan analysis (Level 4)
composer format            # Fix code style with Pint

Run a single test:

vendor/bin/pest tests/Commands/AddChangelogTest.php
vendor/bin/pest --filter="test name"

Architecture

This is a Laravel Package (not an application) — tested via Orchestra Testbench.

Core Workflow

1. changelog:add → writes to resources/.changes/changelog.json (unreleased section)
2. changelog:release → increments version in resources/.version/version.yml, moves unreleased → versioned entry in changelog.json
3. changelog:generate-md → renders CHANGELOG.md via Blade template

Key Components

src/Logic/ — Core logic:

• VersionHandling — reads/writes version.yml, increments versions; registered as singleton
• VersionCalculator — static methods for semver calculations (major/minor/patch/prerelease)
• Version — formats version strings using configurable templates; registered as singleton under releasechangelog.version

src/Commands/ — Artisan commands (all under the changelog:* namespace)

src/Util/:

• FileHandler — central path management for all file operations
• VersionUtil — version update logic by type (patch/minor/major/rc/timestamp)
• Constants — app-wide constants

src/Data/ChangelogItem.php — DTO for individual changelog entries

src/ServiceProvider.php — registers commands, singletons, Blade directive (@releasechangelog), publishes assets

Data Files

resources/.version/version.yml — version state:

major: 1 / minor: 0 / patch: 1 / prerelease: rc / prereleasenumber: 0 / buildmetadata: null

resources/.changes/changelog.json — changelog data:

{
  "unreleased": { "name": "tbd", "release": false, "feat": [...], "modules": [...] },
  "1.0.1.rc0":  { "name": "My First Release", "date": "...", "release": true, "feat": [...] }
}