afuetterer · afuetterer · Feb 2, 2025 · Dec 14, 2024
@@ -0,0 +1,20 @@
+{#
+
+This template is adapted from:
+"python-semantic-release" (MIT License)
+https://github.com/python-semantic-release/python-semantic-release/blob/v9.17.0/src/semantic_release/data/templates/angular/md/.components/changelog_header.md.j2
+
+#}
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). See
+[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit guidelines.
+{%    if ctx.changelog_mode == "update"
+%}{#  # IMPORTANT: add insertion flag for next version update
+#}{{
+        insertion_flag ~ "\n"
+
+}}{%  endif
+%}
@@ -0,0 +1,34 @@
+{#
+
+This template is adapted from:
+"python-semantic-release" (MIT License)
+https://github.com/python-semantic-release/python-semantic-release/blob/v9.17.0/src/semantic_release/data/templates/angular/md/.components/changelog_init.md.j2
+
+#}{#
+This changelog template initializes a full changelog for the project,
+it follows the following logic:
+  1. Header
+  2. Any Unreleased Details (uncommon)
+  3. all previous releases except the very first release
+  4. the first release
+
+#}{#
+   #    Header
+#}{%    include "changelog_header.md.j2"
+%}{#
+   #    Any Unreleased Details (uncommon)
+#}{%    include "unreleased_changes.md.j2"
+%}{#
+    #   Since this is initialization, we are generating all the previous
+    #   release notes per version. The very first release notes is specialized
+#}{%    if releases | length > 0
+%}{%      for release in releases
+%}{%        if loop.last and ctx.mask_initial_release
+%}{%-         include "first_release.md.j2"
+-%}{%       else
+%}{%-         include "versioned_changes.md.j2"
+-%}{%       endif
+%}{{       "\n"
+}}{%      endfor
+%}{%    endif
+%}
@@ -0,0 +1,72 @@
+{#
+
+This template is adapted from:
+"python-semantic-release" (MIT License)
+https://github.com/python-semantic-release/python-semantic-release/blob/v9.17.0/src/semantic_release/data/templates/angular/md/.components/changelog_update.md.j2
+
+#}{#
+This Update changelog template uses the following logic:
+
+  1. Read previous changelog file (ex. project_root/CHANGELOG.md)
+  2. Split on insertion flag (ex. <!-- version list -->)
+  3. Print top half of previous changelog
+  3. New Changes (unreleased commits & newly released)
+  4. Print bottom half of previous changelog
+
+  Note: if a previous file was not found, it does not write anything at the bottom
+        but render does NOT fail
+
+#}{%  set prev_changelog_contents = prev_changelog_file | read_file | safe
+%}{%  set changelog_parts = prev_changelog_contents.split(insertion_flag, maxsplit=1)
+%}{#
+#}{%  if changelog_parts | length < 2
+%}{#    # insertion flag was not found, check if the file was empty or did not exist
+#}{%    if prev_changelog_contents | length > 0
+%}{#      # File has content but no insertion flag, therefore, file will not be updated
+#}{{      changelog_parts[0]
+}}{%    else
+%}{#      # File was empty or did not exist, therefore, it will be created from scratch
+#}{%      include "changelog_init.md.j2"
+%}{%    endif
+%}{%  else
+%}{#
+   #    Previous Changelog Header
+   #      - Depending if there is header content, then it will separate the insertion flag
+   #        with a newline from header content, otherwise it will just print the insertion flag
+#}{%    set prev_changelog_top = changelog_parts[0] | trim
+%}{%    if prev_changelog_top | length > 0
+%}{{
+          "%s\n\n%s\n" | format(prev_changelog_top, insertion_flag | trim)
+
+}}{%    else
+%}{{
+          "%s\n" | format(insertion_flag | trim)
+
+}}{%    endif
+%}{%    if releases | length > 0
+%}{#      # Latest Release Details
+#}{%      set release = releases[0]
+%}{#
+#}{%      if releases | length == 1 and ctx.mask_initial_release
+%}{#        # First Release detected
+#}{{        "\n"
+}}{%-       include "first_release.md.j2"
+-%}{{       "\n"
+}}{#
+#}{%      elif "# " ~ release.version.as_semver_tag() ~ " " not in changelog_parts[1]
+%}{#        # The release version is not already in the changelog so we add it
+#}{{        "\n"
+}}{%-       include "versioned_changes.md.j2"
+-%}{#
+#}{%      endif
+%}{%    endif
+%}{#
+   #    Previous Changelog Footer
+   #      - skips printing footer if empty, which happens when the insertion_flag
+   #        was at the end of the file (ignoring whitespace)
+#}{%    set previous_changelog_bottom = changelog_parts[1] | trim
+%}{%    if previous_changelog_bottom | length > 0
+%}{{      "\n%s\n" | format(previous_changelog_bottom)
+}}{%    endif
+%}{%  endif
+%}
@@ -0,0 +1,93 @@
+{#
+
+This template is adapted from:
+"python-semantic-release" (MIT License)
+https://github.com/python-semantic-release/python-semantic-release/blob/v9.17.0/src/semantic_release/data/templates/angular/md/.components/changes.md.j2
+
+#}{%  from 'macros.md.j2' import apply_alphabetical_ordering_by_brk_descriptions
+%}{%  from 'macros.md.j2' import apply_alphabetical_ordering_by_descriptions
+%}{%  from 'macros.md.j2' import format_breaking_changes_description, format_commit_summary_line
+%}{%  from 'custom.md.j2' import section_heading_order
+%}{#
+EXAMPLE:
+
+### Features
+
+- Add new feature ([#10](https://domain.com/namespace/repo/pull/10),
+  [`abcdef0`](https://domain.com/namespace/repo/commit/HASH))
+
+- **scope**: Add new feature ([`abcdef0`](https://domain.com/namespace/repo/commit/HASH))
+
+### Bug Fixes
+
+- Fix bug ([#11](https://domain.com/namespace/repo/pull/11),
+  [`abcdef1`](https://domain.com/namespace/repo/commit/HASH))
+
+### BREAKING CHANGES
+
+- With the change _____, the change causes ___ effect. Ultimately, this section
+  it is a more detailed description of the breaking change. With an optional
+  scope prefix like the commit messages above.
+
+- **scope**: this breaking change has a scope to identify the part of the code that
+  this breaking change applies to for better context.
+
+#}{%  set max_line_width = max_line_width | default(120)
+%}{%  set hanging_indent = hanging_indent | default(2)
+%}{#
+#}{%  for type_ in section_heading_order if type_ in commit_objects
+%}{#    PREPROCESS COMMITS (order by description & format description line)
+#}{%    set ns = namespace(commits=commit_objects[type_])
+%}{{    apply_alphabetical_ordering_by_descriptions(ns) | default("", true)
+}}{#
+#}{%    set commit_descriptions = []
+%}{#
+#}{%    for commit in ns.commits
+%}{#      # Add reference links to the commit summary line
+#}{%      set description = "- %s" | format(format_commit_summary_line(commit))
+%}{%      set description = description | autofit_text_width(max_line_width, hanging_indent)
+%}{{      commit_descriptions.append(description) | default("", true)
+}}{%    endfor
+%}{#
+   #    # PRINT SECTION (header & commits)
+#}{{    "\n"
+}}{{    "### %s\n" | format(type_ | title)
+}}{{    "\n"
+}}{{    "%s\n" | format(commit_descriptions | unique | join("\n"))
+}}{%  endfor
+-%}
+{#
+   #  # Determine if any commits have a breaking change
+   #  # commit_objects is a dictionary of strings to a list of commits { "Features", [ParsedCommit(), ...] }
+#}{%  set breaking_commits = []
+%}{%  for commits in commit_objects.values()
+%}{#    # Filter out breaking change commits that have no breaking descriptions
+#}{{    breaking_commits.extend(
+          commits | rejectattr("error", "defined") | selectattr("breaking_descriptions.0")
+        ) | default("", true)
+}}{%  endfor
+%}{#
+#}{%  if breaking_commits | length > 0
+%}{#    PREPROCESS COMMITS
+#}{%    set brk_ns = namespace(commits=breaking_commits)
+%}{{    apply_alphabetical_ordering_by_brk_descriptions(brk_ns) | default("", true)
+}}{#
+#}{%    set brking_descriptions = []
+%}{#
+#}{%    for commit in brk_ns.commits
+%}{%      set full_description = "- %s" | format(
+            format_breaking_changes_description(commit).split("\n\n") | join("\n\n- ")
+          )
+%}{{      brking_descriptions.append(
+            full_description | autofit_text_width(max_line_width, hanging_indent)
+          ) | default("", true)
+}}{%    endfor
+%}{#
+   #    # PRINT BREAKING CHANGE DESCRIPTIONS (header & descriptions)
+#}{{    "\n"
+}}{{    "### BREAKING CHANGES\n"
+}}{{
+        "\n%s\n" | format(brking_descriptions | unique | join("\n\n"))
+}}{#
+#}{%  endif
+-%}
@@ -0,0 +1,15 @@
+{# Ref: https://github.com/python-semantic-release/python-semantic-release/issues/1122#issuecomment-2542518505
+
+The types in the section header order corresponds to the ones defined in
+PSR's angular commit parser:
+https://github.com/python-semantic-release/python-semantic-release/blob/7b3f71697ccfbaef884e1e754b6364e974b134cf/src/semantic_release/commit_parser/angular.py#L46
+
+#}
+{% set section_heading_order = [
+    "features",
+    "bug fixes",
+    "performance improvements",
+    "refactoring",
+    "testing",
+    "documentation",
+] %}