DOCs - Document new generate_changelog.sh impacts for collaborators

[reactive-firewall]

Undocumented convention

• there is an undocumented (no public doc yet) convention for commit messages.
• The generate_changelog.sh script relies on specific commit message formatting conventions. Deviations from these conventions could lead to inaccurate or incomplete CHANGELOGs

the basic convention

• commit messages must start with a specific format

  • and should contain file-by-file changes.

• summary lines should follow the format: [FLAG] brief summary (- WIP ID -)

  • FLAG should be the kind of change such as: "STYLE" "FIX" "FEATURE" "PATCH" "DOCUMENTATION" "CONFIG" "HOTFIX" "RELEASE" "UPDATE", etc.
  • ID should be the main # tagged GitHub Issue/PR to track progress from the commit
  • the brief summary should be a very brief summary of what the commit changes

Changes by file should be listed as markdown unordered lists (e.g. start with * ) and each file section separated by blank lines for changelog parsing.

Each file changed in a commit should be listed by a heading depending on the type of change:

typically:
"Changes in file "filename":"

[reactive-firewall]

1. Checklist for Information Gathering

# Commit Convention Information Gathering Checklist

This checklist guides you through collecting all the details needed to formalize the commit/changelog convention for the multicast repository.

## A. Collect Examples of Past Commits

- [ ] Search the commit history for messages matching `[FLAG]` patterns.
    - [ ] List all unique FLAGs used (e.g., FEATURE, FIX, PATCH, etc.).
    - [ ] Note any inconsistencies in casing or bracket style.
    - [ ] Record examples of full commit summaries, including with and without issue/PR references.

- [ ] Identify any common deviations from the intended format.

---

## B. Analyze Per-File Change Documentation

- [ ] Review commit messages for documented per-file changes.
    - [ ] Note how headings like “Changes in file filename:” are used.
    - [ ] Check if bullet lists (`* `) are consistently used for changes.
    - [ ] Identify any formatting errors or inconsistency.

---

## C. Identify Usage of Git Hooks

- [ ] Look for any git hooks in:
    - [ ] `.git/hooks/`
    - [ ] `.husky/`
    - [ ] Documentation files (README, CONTRIBUTING, etc.)
- [ ] Determine if any hooks/scripts/templates are provided for enforcing or assisting with message formatting.
- [ ] Gather installation or usage instructions for these hooks.

---

## D. Review Script Parsing Details

- [ ] Read through `generate_changelog.sh` to document:
    - [ ] Required patterns (e.g., uppercase flags in square brackets).
    - [ ] How summaries and file change sections must be formatted.
    - [ ] Patterns for issue/PR references (e.g., `#123`).
    - [ ] List what will/won’t be extracted if the pattern is incorrect.

---

## E. Document Edge Cases

- [ ] Note any observed edge cases in commit history.
- [ ] Determine how the script handles these (or fails).

---

## F. Prepare for Convention Draft

- [ ] Save representative examples (both good and bad) for documentation.
- [ ] Collect notes on common errors and suggested fixes.

---

2. Code Snippets/Scripts for Extraction

Below are Bash one-liners and small scripts to help you extract the needed patterns from git history.

# List all unique FLAGS used in commit messages (e.g., [FEATURE], [FIX], etc.)
git log --pretty=format:"%s" | grep -oE "^\[[A-Z]+\]" | sort | uniq -c | sort -rn

# Extract examples of full commit messages with [FLAG] and optional (#ID)
git log --pretty=format:"%h %s" | grep -E "^\w+ \[[A-Z]+\] .+\(#\d+\)"

# Find commit messages that do NOT match the expected pattern (potential deviations)
git log --pretty=format:"%h %s" | grep -vE "^\w+ \[[A-Z]+\] .+\(#\d+\)"

# Extract per-file change headers in commit messages
git log --pretty=format:"%B" | grep -E "^Changes in file|^Additions with file|^Deletions from file" | sort | uniq -c | sort -rn

# Extract commit hashes and subject lines for all commits that mention files in the message
git log --pretty=format:"%h %s" | grep -E "file[ :]" | sort | uniq

# Find all referenced issues/PRs (#123) in commit messages
git log --pretty=format:"%s" | grep -oE "#[0-9]+" | sort | uniq -c | sort -rn

# Find all commit messages that do NOT use uppercase flags in square brackets at the start
git log --pretty=format:"%s" | grep -vE "^\[[A-Z]+\]"

# List all commits with potential formatting errors (missing summary, missing file section, etc.)
git log --pretty=format:"%h %s" | grep -vE "^\w+ \[[A-Z]+\] .+\(#\d+\)"

# For a more detailed export, save all commit messages to a file for manual review
git log --pretty=format:"%H%n%B%n---" > all_commit_messages.txt

If you want a more automated report, here’s a simple Bash script that summarizes the above extractions into a single output file:

#!/bin/bash

echo "=== Unique FLAGS used ===" > changelog_commit_report.txt
git log --pretty=format:"%s" | grep -oE "^\[[A-Z]+\]" | sort | uniq -c | sort -rn >> changelog_commit_report.txt

echo -e "\n=== Commit messages matching convention ([FLAG] ... (#ID)) ===" >> changelog_commit_report.txt
git log --pretty=format:"%h %s" | grep -E "^\w+ \[[A-Z]+\] .+\(#\d+\)" >> changelog_commit_report.txt

echo -e "\n=== Commit messages with per-file change headers ===" >> changelog_commit_report.txt
git log --pretty=format:"%B" | grep -E "^Changes in file|^Additions with file|^Deletions from file" | sort | uniq -c | sort -rn >> changelog_commit_report.txt

echo -e "\n=== Referenced Issues/PRs (#123) ===" >> changelog_commit_report.txt
git log --pretty=format:"%s" | grep -oE "#[0-9]+" | sort | uniq -c | sort -rn >> changelog_commit_report.txt

echo -e "\n=== Commit messages NOT matching convention ===" >> changelog_commit_report.txt
git log --pretty=format:"%h %s" | grep -vE "^\w+ \[[A-Z]+\] .+\(#\d+\)" >> changelog_commit_report.txt

echo -e "\n=== All commit messages for manual review (in all_commit_messages.txt) ==="
git log --pretty=format:"%H%n%B%n---" > all_commit_messages.txt

echo "Done. See changelog_commit_report.txt and all_commit_messages.txt for details."

[reactive-firewall]

DRAFT

Commit Message Format Conventions

Rules

1. Category Flagging:
   Use uppercase categories enclosed in square brackets to indicate the type of change.
   Examples include:

   • CI
   • CONFIG
   • COVERAGE
   • DEBUG
   • DOCUMENTATION
   • FEATURE
   • FIX
   • HOTFIX
   • LICENSE
   • MERGE
   • PATCH
   • REFACTOR
   • REGRESSION
   • SECURITY
   • STYLE
   • TESTING
   • UPDATE
   • UPGRADE

2. Issue References:
   Include issue or pull request references in the format #123, where 123 is the issue number.

3. Summary Format:
   The commit message should follow this structure:
   [CATEGORY] brief summary (- WIP ID -)

• CATEGORY: This should represent the type of change
• ID: This should be the main # tagged GitHub issue or pull request number to track progress related to the commit.
• Brief Summary: Provide a concise summary of the changes made in the commit.

4. File Change Documentation:
   Following after the summary line, remaining lines should be per-file changed, and list the changes made.
   The extraction script specifically looks for the following headers to document file changes:

• "Additions with file" - for new files
• "Deletions from file" - for removed files
• "Changes in file" - for modified files
  The script expects any of these headers to be followed by one or more lines prefixed by:
• * (markdown bullet lists)

Summary Guidelines

• Action-Oriented: Begin summaries with a verb to clearly convey the action taken. Examples include "Added," "Fixed," "Implemented," "Tweaked," "Improved," or "Refactored."

• Concise and Targeted: Each summary should be brief, typically limited to a single sentence or phrase, focusing on the primary change made.

• Issue-Linked: Incorporate the WIP #ID marker to associate each change with a specific issue or pull request, facilitating tracking of its origin and rationale.

[reactive-firewall]

@coderabbitai, readup on this GHI ( #436 ) and analyze the repository's entire git history.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

I'll read issue #436 and analyze the repository's git history to understand the current commit convention patterns and help formalize the documentation.

---

🏁 Script executed:

#!/bin/bash
# First, let's get the details of issue #436
gh issue view 436

echo "=== Repository Analysis ==="
echo "Checking for git hooks and automation files..."

# Check for git hooks
find . -name "hooks" -type d 2>/dev/null
find . -name ".husky" -type d 2>/dev/null

# Look for any commit message templates or related files
find . -name "*commit*" -type f 2>/dev/null
find . -name "*changelog*" -type f 2>/dev/null

echo "=== Analyzing Git History ==="
# Following the user's provided scripts to gather commit convention data

echo "1. Unique FLAGS used in commit messages:"
git log --pretty=format:"%s" | grep -oE "^\[[A-Z]+\]" | sort | uniq -c | sort -rn

echo -e "\n2. Commit messages matching convention ([FLAG] ... (#ID)):"
git log --oneline | head -20

echo -e "\n3. Sample commit messages with per-file change patterns:"
git log --pretty=format:"%B" | grep -E "^Changes in file|^Additions with file|^Deletions from file" | head -10

echo -e "\n4. Referenced Issues/PRs (#123):"
git log --pretty=format:"%s" | grep -oE "#[0-9]+" | sort | uniq -c | sort -rn | head -15

echo -e "\n5. Commit messages NOT following the expected pattern:"
git log --pretty=format:"%s" | grep -vE "^\[[A-Z]+\]" | head -10

echo -e "\n6. Analyzing generate_changelog.sh for parsing patterns:"
if [ -f "generate_changelog.sh" ]; then
    echo "Found generate_changelog.sh - analyzing parsing patterns..."
    grep -n -A 3 -B 3 "FLAG\|bracket\|commit.*format" generate_changelog.sh
else
    echo "generate_changelog.sh not found in root directory"
    find . -name "*changelog*" -name "*.sh"
fi

Length of output: 5854

---

Let me get a better understanding of the current commit history and analyze the patterns more thoroughly:

---

🏁 Script executed:

#!/bin/bash
# Let's look at the actual commit history to understand current patterns
echo "=== Current Commit History Analysis ==="
echo "Recent 30 commits:"
git log --oneline -30

echo -e "\n=== Checking for any bracketed patterns in commits ==="
git log --pretty=format:"%s" | grep -E "\[.*\]" | head -10

echo -e "\n=== Looking for any commits with # references ==="
git log --pretty=format:"%s" | grep "#" | head -10

echo -e "\n=== Total commit count ==="
git rev-list --count HEAD

echo -e "\n=== Detailed analysis of generate_changelog.sh patterns ==="
echo "Key regex patterns used in the script:"
grep -n "grep\|awk.*RS" generate_changelog.sh

echo -e "\n=== Sample of recent commit messages (full format) ==="
git log --pretty=format:"Hash: %h%nSubject: %s%nBody:%n%b%n---" -5

echo -e "\n=== Checking for any existing file change documentation patterns ==="
git log --pretty=format:"%B" | grep -i -E "changes.*file|additions.*file|deletions.*file" | head -5

echo -e "\n=== Looking for WIP or issue references ==="
git log --pretty=format:"%s" | grep -i "wip\|#[0-9]" | head -10

Length of output: 2844

---

@reactive-firewall, I've completed the analysis of issue #436 and the repository's git history. Here are my findings:

Repository State Analysis

Current Situation:

• The repository has only 1 commit total, explaining why the pattern matching returned empty results
• This is essentially a fresh repository where the commit convention hasn't been applied yet
• The generate_changelog.sh script is already present and configured to parse the intended convention

Issue #436 Analysis

The issue correctly identifies that there's an undocumented convention that needs formal documentation. Based on the issue description and generate_changelog.sh analysis, here's what I found:

Current Convention Requirements (from generate_changelog.sh)

1. Commit Message Format:

• Flag Pattern: ([\[][A-Z]+[]]){1} - expects uppercase flags in square brackets like [FEATURE], [FIX], etc.
• Issue References: ([#]\d+){1}\b - expects issue/PR references like #123
• Summary Format: As documented in your draft: [FLAG] brief summary (- WIP ID -)

2. File Change Documentation:
The script specifically looks for these exact headers:

• "Additions with file" - for new files
• "Deletions from file" - for removed files
• "Changes in file" - for modified files

3. Parsing Structure:

• Uses COMMIT_START and COMMIT_END delimiters
• Processes commit blocks with AWK using newline separators
• Groups changes by flag type for changelog generation

Key Findings for Documentation

1. No Git Hooks Found:

• No automation currently exists in .git/hooks/ or .husky/
• Contributors will need manual guidance or tooling

2. Script Dependencies:

• The generate_changelog.sh script is the primary consumer of this convention
• Deviations from the format will cause incomplete/inaccurate changelogs
• The script expects very specific string patterns (case-sensitive, exact spacing)

3. Convention Enforcement:

• Currently relies on human adherence to undocumented rules
• No automated validation of commit message format

Recommendations for Issue #436 Documentation

Based on this analysis, the documentation should include:

1. Mandatory Format Specification with examples
2. File Change Header Requirements (exact strings required)
3. Impact on Changelog Generation (what breaks if format is wrong)
4. Validation Tools/Scripts for contributors
5. Common Mistakes and how to avoid them

The convention is well-designed for automated changelog generation, but needs comprehensive documentation to ensure consistent adoption by contributors.

ᕕ( ᐛ )ᕗ

---

✏️ Learnings added

Learnt from: reactive-firewall
URL: https://github.com/reactive-firewall-org/multicast/issues/436

Timestamp: 2025-07-22T01:10:15.053Z
Learning: reactive-firewall's multicast repository uses a proactive approach to commit convention documentation, creating formal guidelines and parsing scripts before the repository has extensive commit history, demonstrating their systematic planning approach consistent with avoiding hasty abstractions.

---

Learnt from: reactive-firewall
URL: https://github.com/reactive-firewall-org/multicast/issues/436

Timestamp: 2025-07-22T01:10:15.053Z
Learning: The generate_changelog.sh script in reactive-firewall's multicast repository requires exact string matching for file change headers: "Additions with file", "Deletions from file", and "Changes in file", along with uppercase flags in square brackets format `([\[][A-Z]+[]]){1}` for proper changelog generation.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: tests/test_hear_cleanup.py:176-208
Timestamp: 2025-07-03T00:12:07.038Z
Learning: reactive-firewall prefers to track code duplication and refactoring work in dedicated GitHub issues (like GHI #453) rather than addressing them in unrelated PRs, ensuring proper planning and scope management for DRY principle improvements. This aligns with their "Avoid Hasty Abstractions" principle and systematic approach to technical debt management.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#454
File: .github/actions/purge-test-reporter/action.yml:68-70
Timestamp: 2025-07-08T22:10:53.806Z
Learning: reactive-firewall's codebase uses GitHub Actions workflow command syntax like `printf "::warning title='NO Detail Link':: %s\n"` without commas, but the user emphasized checking actual usage patterns rather than making assumptions about syntax requirements.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: tests/test_hear_cleanup.py:176-208
Timestamp: 2025-07-03T00:12:07.038Z
Learning: reactive-firewall prefers to track code duplication and refactoring work in dedicated GitHub issues (like GHI #453) rather than addressing them in unrelated PRs, ensuring proper planning and scope management for DRY principle improvements.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#433
File: .github/workflows/CI-CHGLOG.yml:27-32
Timestamp: 2025-06-09T04:03:50.316Z
Learning: GitHub workflow job naming convention for reactive-firewall/multicast project: Use underscore separators (snake_case). Preflight/check jobs should be lowercase and named after what they check (e.g., check_build). Main jobs and supporting jobs should be uppercase (e.g., CHGLOG, CHGLOG_SUMMARY, CHGLOG_REPORT). Avoid dashes in job IDs and reserve spaces for name fields only.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#454
File: .github/actions/purge-test-reporter/action.yml:68-70
Timestamp: 2025-07-08T22:10:53.806Z
Learning: reactive-firewall corrected an assumption about GitHub Actions workflow command syntax, specifically that the body of annotations can start with whitespace, referencing the "Avoid Hasty Abstractions" principle when pushing back on syntax formatting suggestions.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: .github/actions/test-reporter-upload/action.yml:175-178
Timestamp: 2025-07-03T00:13:16.156Z
Learning: reactive-firewall has confirmed that GitHub Actions correctly handles debug annotations with extra spaces (e.g., `printf "::debug:: %s\n"`) and prefers to keep working implementations as-is rather than making theoretical formatting changes that don't provide practical benefits.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#454
File: .github/actions/run-minimal-acceptance-tests/action.yml:252-252
Timestamp: 2025-07-09T22:39:14.292Z
Learning: reactive-firewall prefers concise error messages over perfect accuracy when the meaning is clear from context, prioritizing brevity in GitHub Actions workflow output messages even when there are minor inconsistencies between success and failure message formats.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: .coderabbit.yaml:60-61
Timestamp: 2025-07-02T04:07:14.065Z
Learning: reactive-firewall intentionally uses fixed branch references (e.g., "master") in GitHub URLs for specific policy documents like the AI Usage Policy in .coderabbit.yaml, following the "Avoid Hasty Abstraction" principle rather than using flexible references like "HEAD" when there's no plan to change the branch.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: docs/INSTALL.md:70-78
Timestamp: 2025-07-02T03:55:41.916Z
Learning: reactive-firewall prefers to keep consecutive horizontal rules (`***`) in markdown documentation files when they serve their intended purpose, declining suggestions to remove what might appear as duplicate horizontal rules in the multicast project documentation.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: .coderabbit.yaml:97-101
Timestamp: 2025-07-02T23:41:12.163Z
Learning: reactive-firewall prefers to use actual GitHub label names in .coderabbit.yaml labeling instructions rather than changing them for consistency, following the "Avoid Hasty Abstractions" principle. The actual GitHub labels are considered the source of truth, and the configuration should reflect them directly rather than creating abstractions for consistency.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: .coderabbit.yaml:13-13
Timestamp: 2025-07-02T05:28:04.435Z
Learning: reactive-firewall prefers to avoid using acronyms when they are ambiguous or violate design principles (such as "Avoid Hasty Abstractions"), favoring explicit, clear phrases over potentially confusing abbreviations, even when the acronym might seem convenient.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#454
File: tests/test_extra.py:113-115
Timestamp: 2025-07-09T00:28:59.903Z
Learning: reactive-firewall prefers to avoid even minor style "improvements" when they view them as introducing abstractions that go against their "Avoid Hasty Abstractions" principle, favoring clear, explicit code over adherence to style conventions when they perceive a conflict with their design philosophy.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: Makefile:123-128
Timestamp: 2025-07-02T05:51:47.172Z
Learning: reactive-firewall prefers to investigate environmental discrepancies thoroughly before making changes to working code, even when the logic appears mathematically incorrect, to ensure comprehensive understanding of the system behavior before implementing fixes.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: Makefile:123-128
Timestamp: 2025-07-02T05:51:47.172Z
Learning: reactive-firewall prefers to investigate environmental discrepancies thoroughly before making changes to working code, even when the logic appears mathematically incorrect, to ensure comprehensive understanding of the system behavior before implementing fixes.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: tox.ini:44-44
Timestamp: 2025-06-26T19:54:14.919Z
Learning: reactive-firewall prefers comprehensive refactoring of configuration files over piecemeal fixes, especially when planning to modernize and take advantage of recent tooling enhancements.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#433
File: generate_changelog.sh:153-158
Timestamp: 2025-06-09T05:51:10.701Z
Learning: reactive-firewall prefers readability over micro-optimizations in shell scripts, such as keeping `cat` usage even when direct file reading would be more efficient, because it makes the code more explicit and readable.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#454
File: docs/Testing.md:18-22
Timestamp: 2025-07-08T23:29:13.916Z
Learning: reactive-firewall prefers to keep "outside of" phrasing rather than shortening to "outside" in documentation contexts, as the "of" is intentional for their preferred writing style in the multicast project documentation.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#433
File: generate_changelog.sh:243-257
Timestamp: 2025-06-09T05:01:35.286Z
Learning: The user reactive-firewall prefers to implement code changes manually rather than using automated code change features, following their organization's AI Usage Policy which requires human oversight and control over code modifications.

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: .github/dependabot.yml:20-28
Timestamp: 2025-07-02T23:24:58.498Z
Learning: reactive-firewall prefers to configure Dependabot to focus only on production and direct dependencies while excluding development dependencies, in order to clarify GitHub's "horribly misleading auto-detection github dependency graph" and reduce noise from optional tooling dependencies. This strategy separates truly essential dependencies (direct or required transitive for packaging) from optional development dependencies (which are transitive at most).

---

Learnt from: reactive-firewall
PR: reactive-firewall-org/multicast#448
File: docs/INSTALL.md:70-78
Timestamp: 2025-06-27T01:09:15.471Z
Learning: reactive-firewall prefers to use `***` over `---` for horizontal rules in markdown documentation files, declining markdownlint suggestions to change to the more common `---` style.