High Priority: Create changelog and release communication system

[tbrandenburg]

Problem

No changelog, release notes, or communication mechanism for version changes exists. This significantly harms user confidence and upgrade planning:

• Users cannot understand changes between versions
• Breaking changes may surprise users during upgrades
• Migration planning becomes impossible
• Reduces trust and adoption confidence

Evidence

• No CHANGELOG.md file in repository
• No release notes generation in workflows
• No documentation of breaking changes or migration guides
• README lacks version history or upgrade instructions

Impact

High - Users cannot safely plan upgrades or understand system changes.

Recommended Solution

1. Create CHANGELOG.md with Keep a Changelog format
2. Implement automatic changelog generation from commit messages
3. Document breaking changes and migration steps
4. Include upgrade instructions in README

Acceptance Criteria

• Create CHANGELOG.md following Keep a Changelog format
• Set up automated changelog generation in release workflow
• Document current breaking changes (if any)
• Add upgrade/migration guide to README
• Establish changelog maintenance process
• Include changelog in GitHub Releases

Priority

High - Critical for user confidence and safe upgrades

[github-actions]

Investigation: High Priority: Create changelog and release communication system

Issue: #303 (#303)
Type: ENHANCEMENT
Investigated: 2026-03-29T00:00:00Z

Assessment

Metric	Value	Reasoning
Priority	HIGH	Critical for user confidence and safe upgrades as stated in issue
Complexity	LOW	Only documentation and workflow updates needed; no core code changes
Confidence	HIGH	Clear gap analysis - partial implementation exists, specific missing pieces identified

---

Problem Statement

The issue requests a changelog and release communication system. However, investigation reveals most items are already implemented. The main gap is lack of automated changelog generation from commit messages.

---

Analysis

Change Rationale

The issue claims:

1. ❌ No CHANGELOG.md file
2. ❌ No release notes generation in workflows
3. ❌ No documentation of breaking changes/migration guides
4. ❌ README lacks version history or upgrade instructions

Actual State Found:

1. ✅ CHANGELOG.md EXISTS at root with Keep a Changelog format
2. ⚠️ Release workflow extracts from CHANGELOG.md but doesn't auto-generate from commits
3. ⚠️ Basic version info in README but no detailed migration guide
4. ✅ README has "Releases & Versioning" section (lines 136-176)

Evidence

CHANGELOG.md exists (/home/runner/work/made/made/CHANGELOG.md:1-33):

# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Initial changelog setup

## [v0.1.0] - 2026-03-28
...

Release workflow extracts from CHANGELOG (.github/workflows/release.yml:53-63):

- name: Generate changelog excerpt
  id: changelog
  run: |
    if [ -f CHANGELOG.md ]; then
      # Extract version section from CHANGELOG.md
      sed -n "/## \[${{ steps.version.outputs.version }}\]/,/## \[/p" CHANGELOG.md | head -n -1 > release_notes.md
    else
      echo "Release ${{ steps.version.outputs.version }}" > release_notes.md

README has Releases section (README.md:136-176):

## 📦 Releases & Versioning

This project follows [Semantic Versioning](https://semver.org/) (SemVer).
...

Affected Files

File	Lines	Action	Description
.github/workflows/release.yml	53-76	UPDATE	Add automated changelog generation
README.md	136-176	UPDATE	Add migration/upgrade guide section
CHANGELOG.md	1-33	UPDATE	Document current breaking changes

Integration Points

• Release workflow triggers on tags (v*)
• Makefile has release and tag-release commands
• GitHub Release automatically created by workflow

---

Implementation Plan

Step 1: Add automated changelog generation to release workflow

File: .github/workflows/release.yml
Lines: 53-76
Action: UPDATE

Current code:

      - name: Generate changelog excerpt
        id: changelog
        run: |
          if [ -f CHANGELOG.md ]; then
            # Extract version section from CHANGELOG.md
            sed -n "/## \[${{ steps.version.outputs.version }}\]/,/## \[/p" CHANGELOG.md | head -n -1 > release_notes.md
          else
            echo "Release ${{ steps.version.outputs.version }}" > release_notes.md
            echo "" >> release_notes.md
            echo "See commit history for detailed changes." >> release_notes.md
          fi

Required change:
Add google-changelog or conventional-changelog action before release. Example using metcalfc/changelog-generator:

      - name: Generate changelog
        uses: metcalfc/changelog-generator@v4
        with:
          myToken: ${{ secrets.GITHUB_TOKEN }}
        
      - name: Create/Update CHANGELOG
        run: |
          # Append generated changelog to existing CHANGELOG.md
          # Or use it directly for release notes

Or use conventional-changelog CLI:

      - name: Install conventional-changelog
        run: npm install -g conventional-changelog-cli
        
      - name: Generate changelog
        run: |
          conventional-changelog -p angular -i CHANGELOG.md -s

---

Step 2: Add migration/upgrade guide to README

File: README.md
Lines: After line 176 (end of Releases section)
Action: UPDATE

Add new section:

### Upgrade Guide

#### Upgrading from v0.1.0 to v0.2.0

{List breaking changes and migration steps here}

#### Upgrading from previous versions

1. Check the CHANGELOG.md for version-specific breaking changes
2. Review the commit history for detailed changes
3. Test in a staging environment before production deployment

---

Step 3: Document current breaking changes

File: CHANGELOG.md
Lines: Under [Unreleased] section
Action: UPDATE

Add any known breaking changes:

## [Unreleased]

### Breaking Changes
- {Description of breaking change} - {Migration step}

### Added
- Initial changelog setup

---

Patterns to Follow

From existing release workflow:

# SOURCE: .github/workflows/release.yml:49-63
# Pattern for tag-based release automation
- name: Extract version from tag
  id: version
  run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT

From existing CHANGELOG:

# SOURCE: CHANGELOG.md:1-10
# Pattern for Keep a Changelog format
## [Unreleased]

### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
Conventional commits not used	Use manual CHANGELOG entries as fallback; encourage conventional commits
Breaking changes not documented	Add checklist to release process
Changelog generation conflicts	Use conventional-changelog -p angular -i CHANGELOG.md -s to append rather than overwrite

---

Validation

Automated Checks

# Verify CHANGELOG.md exists and follows format
test -f CHANGELOG.md && echo "CHANGELOG exists"

# Verify release workflow has changelog step
grep -q "changelog" .github/workflows/release.yml

# Test release process locally (dry-run)
git tag -a v0.0.0-test -m "Test release" --dry-run

Manual Verification

1. Create a test tag and verify GitHub Release is created with changelog
2. Verify CHANGELOG.md is updated with new version section
3. Check README for upgrade guide section

---

Scope Boundaries

IN SCOPE:

• Automated changelog generation in release workflow
• Migration/upgrade guide in README
• Document any current breaking changes in CHANGELOG

OUT OF SCOPE (do not touch):

• Core application code
• Test infrastructure changes
• Docker configuration
• Package build processes

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-03-29T00:00:00Z
• Artifact: .ghar/issues/issue-303.md

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.

[github-actions]

🕰️ This issue has been inactive for over 3 days.

@tbrandenburg - Could you provide an update on this issue?

If this issue is resolved or no longer relevant, please consider closing it.