Generate Changelog

Changelog Generator

Generates or updates CHANGELOG.md by extracting and categorizing commits between two git branches or tags. Follows the Keep a Changelog style used by the current repository.

Inputs

Collect from the user (or infer from context):

Path Semantics

• If folder_path points to the repository root, changelog generation covers the entire repository unless a narrower scope is supplied.
• If folder_path points to a subfolder inside the repository, that subfolder becomes the default commit scope automatically.
• If the user wants to write CHANGELOG.md in one location but scope commits to another path, call extract_commits.sh with the repository root as the first argument and the scope path as the optional fourth argument.

Folder Path Resolution

If folder_path is not fully specified:

1. Search by name: If user says "time-series-analytics" but relative path isn't found, search the workspace recursively for a matching folder name.

   find <workspace_root> -type d -name "*time-series-analytics*" 2>/dev/null | head -1

2. Resolve relative paths: If a relative path is given, resolve it from current working directory:

   cd <workspace_root> && realpath <relative_path>

3. Validate: Confirm the folder is a git repository:

   git -C <folder_path> rev-parse --is-inside-work-tree

4. Determine commit scope:

   • If <folder_path> is the repository root, the default scope is the full repository.
   • If <folder_path> is a repository subfolder, use that subfolder as the default scope.
   • If needed, keep both values: repo_root for git operations and scope_path for path-limited history queries.

Version Label Inference

If version_label is not provided, attempt to infer from target_ref:

1. From branch name: Extract version from naming patterns:

   • release-2026.1.0 → 2026.1
   • release-2026.1.0 → 2026.1.0
   • v1.2.0 → 1.2.0
   • v2.0.0-rc1 → 2.0.0-rc1

2. From git tag: If target_ref is a tag like v2.1.0, strip the v prefix.

3. Fallback: If inference fails, ask the user:

   "I couldn't infer a version from <target_ref>. What version label should I use? (e.g., 2026.1.0, v1.2.0)"

If release_date is not provided, use the commit date of the target commit.

GitHub/Remote URL Detection

git -C <folder_path> remote get-url origin

Strip .git suffix. Supports GitHub, GitLab, Gitea, and other hosting platforms.

Workflow

Step 1 – Resolve folder path and validate

1. If folder_path is incomplete or ambiguous, use the folder path resolution logic from the Inputs section.

2. Validate the path is inside a git repository:

   git -C <folder_path> rev-parse --is-inside-work-tree

   If this fails, inform the user the path is not a git repository or repository subfolder.

3. Resolve the repository root and the effective commit scope:

   repo_root=$(git -C <folder_path> rev-parse --show-toplevel)

   Treat <folder_path> as the scope when it is a subfolder. If <folder_path> equals repo_root, use the full repository unless the user supplied a narrower scope.

4. Verify both base_ref and target_ref exist:

   git -C "$repo_root" rev-parse <base_ref> >/dev/null 2>&1
   git -C "$repo_root" rev-parse <target_ref> >/dev/null 2>&1

   If either fails, list available branches and tags:

   git -C "$repo_root" branch -a && git -C "$repo_root" tag

Step 2 – Infer version and release date

1. If version_label is missing, apply the version inference logic from the Inputs section.
2. If release_date is missing, extract the commit date of target_ref:

   git -C "$repo_root" log -1 --format=%cs <target_ref>

   Format as "Month Year" (e.g., "June 2026").

Step 3 – Detect existing CHANGELOG format

Before categorizing commits, read the existing CHANGELOG.md (if present):

1. Check if <folder_path>/CHANGELOG.md exists.

2. If it exists, analyze its structure:

   • Look for section headers: Scan for patterns like ## [Version], ### Added, ### Fixed, etc.
   • Infer category order: Note which sections appear and in what order.
   • Detect categorization style: Is it Keep a Changelog style? Custom sections? Hybrid?
   • Example inference:

     # Changelog
     ## [2.0.0]
     ### Added
     ### Changed
     ### Fixed

     → Infer: Use Added, Changed, Fixed (no Security, Documentation, Removed)

3. If no CHANGELOG.md exists or it has no clear structure, use the default keyword-based categorization (described in Step 4).

Step 4 – Extract and categorize commits

1. Get the commit list between base and target refs:

    bash .github/skills/generate-changelog/scripts/extract_commits.sh \
       <folder_path> <base_ref> <target_ref> [scope_path]

   Usage notes:

   • Use <folder_path> only for full-repository changelogs when it points to the repo root.
   • Use a repository subfolder as <folder_path> for folder-specific changelogs.
   • Use [scope_path] only when <folder_path> is the repo root but commit extraction should be narrowed to a different path.

2. For each commit, classify into a section based on the detected format from Step 3.

3. If using default keyword-based categorization, apply these rules in order (first match wins):

   Section	Keywords / patterns (case-insensitive)
   Security	security, cve, vulnerability, bump, trivy, patch, upgrade (dependency)
   Fixed	fix, fixed, repair, resolve, hotfix, revert
   Added	add, added, new, introduce, enable, support, feature, implement
   Removed	remove, removed, delete, deleted, drop, deprecat
   Documentation	doc, docs, documentation, readme, changelog, typo, spelling
   Changed	everything else

   [!TIP] If a commit is ambiguous, prefer the section that better serves the reader. Merge commits and automated bot commits (e.g., Dependabot) should go in Security or Changed as appropriate.

4. Also collect PR numbers referenced in commit messages (pattern (#\d+) or #\d+).