python-semantic-release 9.8.9__py3-none-any.whl → 9.10.0__py3-none-any.whl

{python_semantic_release-9.8.9.dist-info → python_semantic_release-9.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-semantic-release
-Version: 9.8.9
+Version: 9.10.0
 Summary: Automatic Semantic Versioning for Python projects
 Author-email: Rolf Erik Lekang <me@rolflekang.com>
 License: MIT

{python_semantic_release-9.8.9.dist-info → python_semantic_release-9.10.0.dist-info}/RECORD

@@ -1,38 +1,44 @@
-semantic_release/__init__.py,sha256=-j2xgGDaUpspgWKkRjUOgjqDE_juW0rpZYVdkhnnjWc,1228
+semantic_release/__init__.py,sha256=C5zv3UkZdzyn-xzqjsl6ltjgVx_HcwOtrPym3F0BF5I,1229
 semantic_release/__main__.py,sha256=blPn7CMpuSe4Z-GBIDv0QA0OEDTMGU-7edsLRkkhPR4,120
 semantic_release/const.py,sha256=Z1o2QNh60wSLeF-_1TemMBjU3ZXbV0XghnUFsbTVfOs,831
 semantic_release/enums.py,sha256=D5B_reQGGKQQT22HO5PUtvn2Bok3fkht6TfJtXkmAUg,1020
-semantic_release/errors.py,sha256=bPQDMW9MVhCwkE_TrpsmsRYZRuk5iOnqi-hKeujXQc0,2676
+semantic_release/errors.py,sha256=rco5-lwz_0JbJrDsQWmTvT_l3bA3HFkeTmBiZfvCx-Q,2799
 semantic_release/gitproject.py,sha256=izWc4NLdUzAwxGG_fJeqqHW9ivSrPcWBzSaOijQx4f8,8564
 semantic_release/helpers.py,sha256=d1jOX0SNyqPc_3wr14xR25FfpqhMd4Ev7MNBOWlScc0,5581
 semantic_release/changelog/__init__.py,sha256=Bg6Xe5Vt32rWoMscW-hd4sUwiZqzWmsg4CD1EhMesMY,262
-semantic_release/changelog/context.py,sha256=8cbOv9cB9Ji7xjRn4-YUUHBfg9LLfSwmmXuZpqEmvns,1653
+semantic_release/changelog/context.py,sha256=zvkjQ9qv5Jk1IPZOnPPh1spM9AiWVYctJfMbI8L_qaI,2403
 semantic_release/changelog/release_history.py,sha256=9gJxqOKPF9HjmOdXW-k-dWbe2YGWxqZEOWSSef-qwoE,7050
-semantic_release/changelog/template.py,sha256=JqZcjdozM9-059Sa8PfiHxYNeyZFa0jxk_beyRLv5sU,4640
+semantic_release/changelog/template.py,sha256=FfA5-6sWh3bYQ5sEK4fR414_WNxm3TPUXghqak_9eyk,5989
 semantic_release/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-semantic_release/cli/changelog_writer.py,sha256=OVuRI7RTMsMGIaxyEN4kb8N4j08OHNvSyRyj6iBR_ME,5162
+semantic_release/cli/changelog_writer.py,sha256=tvUtUFfxP4mKHLfWiC2yGrdCNMtUHQrpFxfdNpGTam4,8630
 semantic_release/cli/cli_context.py,sha256=23eyV6KWIpUckUSWILEd7t9dixp-QCY5-kGZnyucEYY,4114
-semantic_release/cli/config.py,sha256=bI0v896k0mheNn6_yZpYp6D-q83hx0gcddqYkyJejdo,24845
-semantic_release/cli/const.py,sha256=S8oNNpSaKdZxcAs7PAKEjQHic0czoJBGd7XHo57FOzw,39
-semantic_release/cli/github_actions_output.py,sha256=Wy4jEIpSFgoMyJqq4FD7scIpgovivutFLZ7Fs4y2CUY,2110
+semantic_release/cli/config.py,sha256=wu_ytryKW9jOAb649pkjlrAfwlLDuE83GPODtdmXHpA,26632
+semantic_release/cli/const.py,sha256=haTpNlJifrtbwICwF1u0MNyB0kDsqGUsfM2zwuDu4RM,162
+semantic_release/cli/github_actions_output.py,sha256=VYIOb5x5h8eEJdSlXM_mkhT9xXtYi-RgxvnoM7iUn8s,2288
 semantic_release/cli/masking_filter.py,sha256=DxqjiJyABlzwwwZ1r8JGQpb6QrF00StJFm0-2-s5Fv0,3071
 semantic_release/cli/util.py,sha256=FyXaBkeL7nXKjy3X9rQLEwvn7p46xPekp2V8Z-5MVrk,3755
 semantic_release/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-semantic_release/cli/commands/changelog.py,sha256=bqnJwv0pgvEOroZEMixEa8IUby-cvgIirXRz31FlnV0,3716
+semantic_release/cli/commands/changelog.py,sha256=kVHcGdfud74-M6hjWf1PS6l95gD4yUlu3CZGBkCt7aY,3765
 semantic_release/cli/commands/generate_config.py,sha256=2xZOu3NpyhBp0pWr7d8ugKl_kjqQgpSsSMHq5wHTfrE,1699
 semantic_release/cli/commands/main.py,sha256=kqO8bZw9Nv6T5QkIl53zzmH2rd4LuLoA8agweH0VYPY,4022
 semantic_release/cli/commands/publish.py,sha256=SZQlIewvqyIC14dkIIVVFetE0tPsKbO1cUyxnZsicrw,2845
-semantic_release/cli/commands/version.py,sha256=UjjBlv2IQs21LRQ3APeRUXwjZ20MXMBXBhykzGjj46c,24231
+semantic_release/cli/commands/version.py,sha256=4ZfF2zbwnSNlVewfyXI1UrlvxJJFSI3A3xGo6Vg8CC0,24270
 semantic_release/commit_parser/__init__.py,sha256=cv5HFBdw7OJd4Laj4Ex8ZZ5Tml8GwXgQcXW6Pasr2Ao,615
 semantic_release/commit_parser/_base.py,sha256=t-Z9ALgAe7aZpYXz1mk3Fe-uAvipgKdNrq4Okg_WW9c,3026
-semantic_release/commit_parser/angular.py,sha256=ERWeTBTFNIBOaTIopY4Vff0KbeFwrSQWbADe3smVW-8,4579
+semantic_release/commit_parser/angular.py,sha256=AbclYVP_aX_WKpwBCN7SCyJ3-aYf-SVOT4O5TOBLVwI,4857
 semantic_release/commit_parser/emoji.py,sha256=M6zgqsXqegLK5FxZGyfsOPM3vOsJkPKVAjnGATOhwa4,3452
 semantic_release/commit_parser/scipy.py,sha256=AH_GeMZ9hWiNQTL78bovpQy7mBeobGpUk5Shzyxxm6c,5951
 semantic_release/commit_parser/tag.py,sha256=SAop9INQvKOwktNmVypKFngd6xHmY_XZrLUWChUjz84,3353
 semantic_release/commit_parser/token.py,sha256=BB4ZCyt753CCaBFF95cQ4sFm6Au96wpO0YyTAWdcOvE,1609
 semantic_release/commit_parser/util.py,sha256=vLcVDErZrExM55jMffos0hyMbNVQoJ-PeeVDG1Ej51I,730
-semantic_release/data/templates/CHANGELOG.md.j2,sha256=4SNA1uTM2_qLA_3QTbS8JHZi9tB-21gCzLjkj_U20JI,1069
-semantic_release/data/templates/release_notes.md.j2,sha256=27uIHgG6iYmqdMaoWFP5LJRZcrO-3paqFzHHHsGpXXE,465
+semantic_release/data/templates/angular/release_notes.md.j2,sha256=ftg0pFkmGYlb9UH2waSLc6neC8rPMMCqblJaQeq4vTg,46
+semantic_release/data/templates/angular/md/.changelog_header.md.j2,sha256=qNxTuSr59CV_yyimVU_RYp5azCnK0l6nJ03Zf0u5Ugg,166
+semantic_release/data/templates/angular/md/.changelog_init.md.j2,sha256=mIV6AuZmB6BGl_hBDGM9ea_CG5BV7HqI3Ko9jsn7zMs,602
+semantic_release/data/templates/angular/md/.changelog_update.md.j2,sha256=DHY4K_EQPXGHNHVbsVI5l3x_IWNtYq3IyHFyFsNnLe0,2387
+semantic_release/data/templates/angular/md/.changes.md.j2,sha256=oC2amekjxsNjgj0BkVzs6ANswxntOi3ItlQd9VtbVm8,339
+semantic_release/data/templates/angular/md/.unreleased_changes.md.j2,sha256=8CGiPvJEzrjNyqdDFjRGNlLpjIFGiMccPKPmi-vdGTI,178
+semantic_release/data/templates/angular/md/.versioned_changes.md.j2,sha256=K2J5GHTBUffPxZ-FSoewHkwNJtuPidZA83hEGtpk7rg,258
+semantic_release/data/templates/angular/md/CHANGELOG.md.j2,sha256=LjSFwb3QROfj3PZY-2qeMBSlbnP7vf2L9Qc_4-FX68Y,816
 semantic_release/hvcs/__init__.py,sha256=JwoaLOF-12L-OBo_9-tOXXhdiHKeVungA9865to2oZk,494
 semantic_release/hvcs/_base.py,sha256=9-iTqTPSbiEevKbCBP9K2hq4c-2T4wPbeLWe-kAxBzo,2607
 semantic_release/hvcs/bitbucket.py,sha256=nqlOmeNda0sRSEBGWMluphy1KlpRTQrHV7itxf0IXE0,9266
@@ -47,10 +53,10 @@ semantic_release/version/algorithm.py,sha256=ofx_bIWq6ptJVr-ekI11IzxzDEctDKFiVwa
 semantic_release/version/declaration.py,sha256=f6Ld7hIhrqvDrRBapJHr-KDimuyo-4IG8009Zu9BIgU,7357
 semantic_release/version/translator.py,sha256=P1noIsVBn8u6zNOFjG0xKYOWapxqf_PHSMvMeLJ9kXg,3050
 semantic_release/version/version.py,sha256=6PCtSbLP88U1daoxnCwHc--YguZo4waGNLqJ5JfeczE,14175
-python_semantic_release-9.8.9.dist-info/AUTHORS.rst,sha256=XOReVvpymEFUPsS2QPH97jlfJBVrxwS2eu8-jVAe4gk,230
-python_semantic_release-9.8.9.dist-info/LICENSE,sha256=NE85nszX252sdQdu0xgS9qwfYES0k8qS6gW3uO4jRGE,1083
-python_semantic_release-9.8.9.dist-info/METADATA,sha256=3vX4dbgkjDIpnkV6VcdaH3-MZlolfjyRicLgmGmoos0,3520
-python_semantic_release-9.8.9.dist-info/WHEEL,sha256=eOLhNAGa2EW3wWl_TU484h7q1UNgy0JXjjoqKoxAAQc,92
-python_semantic_release-9.8.9.dist-info/entry_points.txt,sha256=6bS6euSagjerp7onDtfI9_ZpczWreZF3gjHfGAegkbo,123
-python_semantic_release-9.8.9.dist-info/top_level.txt,sha256=qYA24nyg3eP-ti5UW7Vuj2aXVmM0wqVHx4mREdRZNAA,17
-python_semantic_release-9.8.9.dist-info/RECORD,,
+python_semantic_release-9.10.0.dist-info/AUTHORS.rst,sha256=XOReVvpymEFUPsS2QPH97jlfJBVrxwS2eu8-jVAe4gk,230
+python_semantic_release-9.10.0.dist-info/LICENSE,sha256=NE85nszX252sdQdu0xgS9qwfYES0k8qS6gW3uO4jRGE,1083
+python_semantic_release-9.10.0.dist-info/METADATA,sha256=Oa_kotAU8xlkMsUejoXJQ2XEJwoPWw4HBWPhTtx-tEM,3521
+python_semantic_release-9.10.0.dist-info/WHEEL,sha256=eOLhNAGa2EW3wWl_TU484h7q1UNgy0JXjjoqKoxAAQc,92
+python_semantic_release-9.10.0.dist-info/entry_points.txt,sha256=6bS6euSagjerp7onDtfI9_ZpczWreZF3gjHfGAegkbo,123
+python_semantic_release-9.10.0.dist-info/top_level.txt,sha256=qYA24nyg3eP-ti5UW7Vuj2aXVmM0wqVHx4mREdRZNAA,17
+python_semantic_release-9.10.0.dist-info/RECORD,,

semantic_release/__init__.py

@@ -24,7 +24,7 @@ from semantic_release.version import (
     tags_and_versions,
 )
 
-__version__ = "9.8.9"
+__version__ = "9.10.0"
 
 __all__ = [
     "CommitParser",

semantic_release/changelog/context.py

@@ -1,7 +1,11 @@
 from __future__ import annotations
 
+import logging
+import os
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Callable
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Literal
 
 if TYPE_CHECKING:
     from jinja2 import Environment
@@ -34,28 +38,53 @@ class ReleaseNotesContext:
         return env
 
 
+class ChangelogMode(Enum):
+    INIT = "init"
+    UPDATE = "update"
+
+
 @dataclass
 class ChangelogContext:
     repo_name: str
     repo_owner: str
     hvcs_type: str
     history: ReleaseHistory
+    changelog_mode: Literal["update", "init"]
+    prev_changelog_file: str
+    changelog_insertion_flag: str
     filters: tuple[Callable[..., Any], ...] = ()
 
     def bind_to_environment(self, env: Environment) -> Environment:
         env.globals["context"] = self
+        env.globals["ctx"] = self
         for f in self.filters:
             env.filters[f.__name__] = f
         return env
 
 
 def make_changelog_context(
-    hvcs_client: HvcsBase, release_history: ReleaseHistory
+    hvcs_client: HvcsBase,
+    release_history: ReleaseHistory,
+    mode: ChangelogMode,
+    prev_changelog_file: Path,
+    insertion_flag: str,
 ) -> ChangelogContext:
     return ChangelogContext(
         repo_name=hvcs_client.repo_name,
         repo_owner=hvcs_client.owner,
         history=release_history,
+        changelog_mode=mode.value,
+        changelog_insertion_flag=insertion_flag,
+        prev_changelog_file=str(prev_changelog_file),
         hvcs_type=hvcs_client.__class__.__name__.lower(),
-        filters=(*hvcs_client.get_changelog_context_filters(),),
+        filters=(*hvcs_client.get_changelog_context_filters(), read_file),
     )
+
+
+def read_file(filepath: str) -> str:
+    try:
+        with Path(filepath).open(newline=os.linesep) as rfd:
+            return rfd.read()
+    except FileNotFoundError as err:
+        logging.warning(err)
+        return ""

semantic_release/changelog/template.py

@@ -3,8 +3,8 @@ from __future__ import annotations
 import logging
 import os
 import shutil
-from pathlib import Path
-from typing import TYPE_CHECKING, Callable, Iterable
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
 
 from jinja2 import FileSystemLoader
 from jinja2.sandbox import SandboxedEnvironment
@@ -12,7 +12,7 @@ from jinja2.sandbox import SandboxedEnvironment
 from semantic_release.helpers import dynamic_import
 
 if TYPE_CHECKING:
-    from typing import Literal
+    from typing import Callable, Iterable, Literal
 
     from jinja2 import Environment
 
@@ -56,7 +56,7 @@ def environment(
         autoescape_value = autoescape
     log.debug("%s", locals())
 
-    return SandboxedEnvironment(
+    return ComplexDirectorySandboxedEnvironment(
         block_start_string=block_start_string,
         block_end_string=block_end_string,
         variable_start_string=variable_start_string,
@@ -75,6 +75,23 @@ def environment(
     )
 
 
+class ComplexDirectorySandboxedEnvironment(SandboxedEnvironment):
+    def join_path(self, template: str, parent: str) -> str:
+        """
+        Add support for complex directory structures in the template directory.
+
+        This method overrides the default functionality of the SandboxedEnvironment
+        where all 'include' keywords expect to be in the same directory as the calling
+        template, however this is unintuitive when using a complex directory structure.
+
+        This override simulates the changing of directories when you include the template
+        from a child directory. When the child then includes a template, it will make the
+        path relative to the child directory rather than the top level template directory.
+        """
+        # Must be posixpath because jinja only knows how to handle posix path includes
+        return str(PurePosixPath(parent).parent / template)
+
+
 # pylint: disable=redefined-outer-name
 def recursive_render(
     template_dir: Path,
@@ -107,11 +124,15 @@ def recursive_render(
             src_file_path = str((root / file).relative_to(template_dir))
             output_file_path = str((output_path / output_filename).resolve())
 
+            # Although, file stream rendering is possible and preferred in most
+            # situations, here it is not desired as you cannot read the previous
+            # contents of a file during the rendering of the template. This mechanism
+            # is used for inserting into a current changelog. When using stream rendering
+            # of the same file, it always came back empty
             log.debug("rendering %s to %s", src_file_path, output_file_path)
-            stream = environment.get_template(src_file_path).stream()
-
-            with open(output_file_path, "wb+") as output_file:
-                stream.dump(output_file, encoding="utf-8")
+            rendered_file = environment.get_template(src_file_path).render()
+            with open(output_file_path, "w", encoding="utf-8") as output_file:
+                output_file.write(rendered_file)
 
             rendered_paths.append(output_file_path)
         else:

semantic_release/cli/changelog_writer.py

@@ -1,60 +1,108 @@
 from __future__ import annotations
 
+import os
+from contextlib import suppress
 from logging import getLogger
-from os import listdir
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 # NOTE: use backport with newer API than stdlib
 from importlib_resources import files
 
+import semantic_release
 from semantic_release.changelog.context import (
     ReleaseNotesContext,
     make_changelog_context,
 )
 from semantic_release.changelog.template import environment, recursive_render
+from semantic_release.cli.const import (
+    DEFAULT_CHANGELOG_NAME_STEM,
+    DEFAULT_RELEASE_NOTES_TPL_FILE,
+    JINJA2_EXTENSION,
+)
 from semantic_release.cli.util import noop_report
+from semantic_release.errors import InternalError
 
 if TYPE_CHECKING:
     from jinja2 import Environment
 
+    from semantic_release.changelog.context import ChangelogContext
     from semantic_release.changelog.release_history import Release, ReleaseHistory
-    from semantic_release.cli.config import RuntimeContext
+    from semantic_release.cli.config import ChangelogOutputFormat, RuntimeContext
     from semantic_release.hvcs._base import HvcsBase
 
 
 log = getLogger(__name__)
 
 
-def get_release_notes_template(template_dir: Path) -> str:
-    """Read the project's template for release notes, falling back to the default."""
-    fname = template_dir / ".release_notes.md.j2"
-    try:
-        return fname.read_text(encoding="utf-8")
-    except FileNotFoundError:
-        return (
-            files("semantic_release")
-            .joinpath("data/templates/release_notes.md.j2")
-            .read_text(encoding="utf-8")
+def get_default_tpl_dir(style: str, sub_dir: str | None = None) -> Path:
+    module_base_path = Path(str(files(semantic_release.__name__)))
+    default_templates_path = module_base_path.joinpath(
+        f"data/templates/{style}",
+        "" if sub_dir is None else sub_dir.strip("/"),
+    )
+
+    if default_templates_path.is_dir():
+        return default_templates_path
+
+    raise InternalError(
+        str.join(
+            " ",
+            [
+                "Default template directory not found at",
+                f"{default_templates_path}. Installation corrupted!",
+            ],
         )
+    )
 
 
-def render_default_changelog_file(template_env: Environment) -> str:
-    changelog_text = (
-        files("semantic_release")
-        .joinpath("data/templates/CHANGELOG.md.j2")
-        .read_text(encoding="utf-8")
+def render_default_changelog_file(
+    output_format: ChangelogOutputFormat,
+    changelog_context: ChangelogContext,
+    changelog_style: str,
+) -> str:
+    tpl_dir = get_default_tpl_dir(style=changelog_style, sub_dir=output_format.value)
+    changelog_tpl_file = Path(DEFAULT_CHANGELOG_NAME_STEM).with_suffix(
+        str.join(".", ["", output_format.value, JINJA2_EXTENSION.lstrip(".")])
+    )
+
+    # Create a new environment as we don't want user's configuration as it might
+    # not match our default template structure
+    template_env = changelog_context.bind_to_environment(
+        environment(
+            autoescape=False,
+            newline_sequence="\n",
+            template_dir=tpl_dir,
+        )
+    )
+
+    # Using the proper enviroment with the changelog context, render the template
+    template = template_env.get_template(str(changelog_tpl_file))
+    changelog_content = template.render().rstrip()
+
+    # Normalize line endings to ensure universal newlines because that is what is expected
+    # of the content when we write it to a file. When using pathlib.Path.write_text(), it
+    # will automatically normalize the file to the OS. At this point after render, we may
+    # have mixed line endings because of the read_file() call of the previous changelog
+    # (which may be /r/n or /n)
+    return str.join(
+        "\n", [line.replace("\r", "") for line in changelog_content.split("\n")]
     )
-    template = template_env.from_string(changelog_text)
-    return template.render().rstrip()
 
 
 def render_release_notes(
-    release_notes_template: str,
+    release_notes_template_file: str,
     template_env: Environment,
 ) -> str:
-    template = template_env.from_string(release_notes_template)
-    return template.render().rstrip()
+    # NOTE: release_notes_template_file must be a relative path to the template directory
+    # because jinja2's filtering and template loading filter is janky
+    template = template_env.get_template(release_notes_template_file)
+    release_notes = template.render().rstrip() + os.linesep
+
+    # Normalize line endings to match the current platform
+    return str.join(
+        os.linesep, [line.replace("\r", "") for line in release_notes.split("\n")]
+    )
 
 
 def apply_user_changelog_template_directory(
@@ -85,7 +133,9 @@ def apply_user_changelog_template_directory(
 def write_default_changelog(
     changelog_file: Path,
     destination_dir: Path,
-    environment: Environment,
+    output_format: ChangelogOutputFormat,
+    changelog_context: ChangelogContext,
+    changelog_style: str,
     noop: bool = False,
 ) -> str:
     if noop:
@@ -98,9 +148,15 @@ def write_default_changelog(
                 ],
             )
         )
-    else:
-        changelog_text = render_default_changelog_file(environment)
-        changelog_file.write_text(f"{changelog_text}\n", encoding="utf-8")
+        return str(changelog_file)
+
+    changelog_text = render_default_changelog_file(
+        output_format=output_format,
+        changelog_context=changelog_context,
+        changelog_style=changelog_style,
+    )
+    # write_text() will automatically normalize newlines to the OS, so we just use an universal newline here
+    changelog_file.write_text(f"{changelog_text}\n", encoding="utf-8")
 
     return str(changelog_file)
 
@@ -117,19 +173,34 @@ def write_changelog_files(
     changelog_context = make_changelog_context(
         hvcs_client=hvcs_client,
         release_history=release_history,
+        mode=runtime_ctx.changelog_mode,
+        insertion_flag=runtime_ctx.changelog_insertion_flag,
+        prev_changelog_file=runtime_ctx.changelog_file,
     )
 
-    changelog_context.bind_to_environment(runtime_ctx.template_environment)
+    user_templates = []
 
-    use_user_template_dir = bool(
-        # Directory exists and directory is not empty
-        template_dir.exists() and template_dir.is_dir() and listdir(template_dir)
-    )
+    # Update known templates list if Directory exists and directory has actual files to render
+    if template_dir.is_dir():
+        user_templates.extend(
+            [
+                f
+                for f in template_dir.rglob("*")
+                if f.is_file() and f.suffix == JINJA2_EXTENSION
+            ]
+        )
 
-    if use_user_template_dir:
+        with suppress(ValueError):
+            # do not include a release notes override when considering number of changelog templates
+            user_templates.remove(template_dir / f".{DEFAULT_RELEASE_NOTES_TPL_FILE}")
+
+    # Render user templates if found
+    if len(user_templates) > 0:
         return apply_user_changelog_template_directory(
             template_dir=template_dir,
-            environment=runtime_ctx.template_environment,
+            environment=changelog_context.bind_to_environment(
+                runtime_ctx.template_environment
+            ),
             destination_dir=project_dir,
             noop=noop,
         )
@@ -139,7 +210,9 @@ def write_changelog_files(
         write_default_changelog(
             changelog_file=runtime_ctx.changelog_file,
             destination_dir=project_dir,
-            environment=runtime_ctx.template_environment,
+            output_format=runtime_ctx.changelog_output_format,
+            changelog_context=changelog_context,
+            changelog_style=runtime_ctx.changelog_style,
             noop=noop,
         )
     ]
@@ -150,7 +223,22 @@ def generate_release_notes(
     release: Release,
     template_dir: Path,
     history: ReleaseHistory,
+    style: str,
 ) -> str:
+    users_tpl_file = template_dir / f".{DEFAULT_RELEASE_NOTES_TPL_FILE}"
+
+    # Determine if the user has a custom release notes template or we should use
+    # the default template directory with our default release notes template
+    tpl_dir = (
+        template_dir if users_tpl_file.is_file() else get_default_tpl_dir(style=style)
+    )
+
+    release_notes_tpl_file = (
+        users_tpl_file.name
+        if users_tpl_file.is_file()
+        else DEFAULT_RELEASE_NOTES_TPL_FILE
+    )
+
     release_notes_env = ReleaseNotesContext(
         repo_name=hvcs_client.repo_name,
         repo_owner=hvcs_client.owner,
@@ -161,7 +249,7 @@ def generate_release_notes(
     ).bind_to_environment(
         # Use a new, non-configurable environment for release notes -
         # not user-configurable at the moment
-        environment(template_dir=template_dir)
+        environment(autoescape=False, template_dir=tpl_dir)
     )
 
     # TODO: Remove in v10
@@ -170,6 +258,6 @@ def generate_release_notes(
     }
 
     return render_release_notes(
-        release_notes_template=get_release_notes_template(template_dir),
+        release_notes_template_file=release_notes_tpl_file,
         template_env=release_notes_env,
     )

semantic_release/cli/commands/changelog.py

@@ -43,7 +43,9 @@ def post_release_notes(
         return
 
     hvcs_client.create_or_update_release(
-        release_tag, f"{release_notes}\n", prerelease=prerelease
+        release_tag,
+        release_notes,
+        prerelease=prerelease,
     )
 
 
@@ -116,6 +118,7 @@ def changelog(cli_ctx: CliContextObj, release_tag: str | None) -> None:
         release,
         runtime.template_dir,
         release_history,
+        style=runtime.changelog_style,
     )
 
     try:

semantic_release/cli/commands/version.py

@@ -706,6 +706,7 @@ def version(  # noqa: C901
         release_history.released[new_version],
         runtime.template_dir,
         history=release_history,
+        style=runtime.changelog_style,
     )
 
     exception: Exception | None = None

semantic_release/cli/config.py

@@ -27,6 +27,7 @@ from urllib3.util.url import parse_url
 
 from semantic_release import hvcs
 from semantic_release.changelog import environment
+from semantic_release.changelog.context import ChangelogMode
 from semantic_release.cli.const import DEFAULT_CONFIG_FILE
 from semantic_release.cli.masking_filter import MaskingFilter
 from semantic_release.commit_parser import (
@@ -94,6 +95,13 @@ class EnvConfigVar(BaseModel):
 MaybeFromEnv = Union[EnvConfigVar, str]
 
 
+class ChangelogOutputFormat(str, Enum):
+    """Supported changelog output formats when using the default templates."""
+
+    MARKDOWN = "md"
+    # RESTRUCTURED_TEXT = "rst"
+
+
 class ChangelogEnvironmentConfig(BaseModel):
     block_start_string: str = "{%"
     block_end_string: str = "%}"
@@ -108,14 +116,26 @@ class ChangelogEnvironmentConfig(BaseModel):
     newline_sequence: Literal["\n", "\r", "\r\n"] = "\n"
     keep_trailing_newline: bool = False
     extensions: Tuple[str, ...] = ()
-    autoescape: Union[bool, str] = True
+    autoescape: Union[bool, str] = False
+
+
+class DefaultChangelogTemplatesConfig(BaseModel):
+    # TODO: BREAKING CHANGE v10
+    # changelog_file: str = "CHANGELOG.md"
+    output_format: ChangelogOutputFormat = ChangelogOutputFormat.MARKDOWN
 
 
 class ChangelogConfig(BaseModel):
-    template_dir: str = "templates"
+    # TODO: BREAKING CHANGE v10, move to DefaultChangelogTemplatesConfig
     changelog_file: str = "CHANGELOG.md"
-    exclude_commit_patterns: Tuple[str, ...] = ()
+    default_templates: DefaultChangelogTemplatesConfig = (
+        DefaultChangelogTemplatesConfig()
+    )
     environment: ChangelogEnvironmentConfig = ChangelogEnvironmentConfig()
+    exclude_commit_patterns: Tuple[str, ...] = ()
+    mode: ChangelogMode = ChangelogMode.INIT
+    insertion_flag: str = "<!-- version list -->"
+    template_dir: str = "templates"
 
 
 class BranchConfig(BaseModel):
@@ -386,7 +406,11 @@ class RuntimeContext:
     changelog_excluded_commit_patterns: Tuple[re.Pattern[str], ...]
     version_declarations: Tuple[VersionDeclarationABC, ...]
     hvcs_client: hvcs.HvcsBase
+    changelog_insertion_flag: str
+    changelog_mode: ChangelogMode
     changelog_file: Path
+    changelog_style: str
+    changelog_output_format: ChangelogOutputFormat
     ignore_token_for_push: bool
     template_environment: Environment
     template_dir: Path
@@ -640,6 +664,18 @@ class RuntimeContext:
 
             build_cmd_env[name] = env_val
 
+        # TODO: better support for custom parsers that actually just extend defaults
+        #
+        # Here we just assume the desired changelog style matches the parser name
+        # as we provide templates specific to each parser type. Unfortunately if the user has
+        # provided a custom parser, it would be up to the user to provide custom templates
+        # but we just assume the base template is angular
+        # changelog_style = (
+        #     raw.commit_parser
+        #     if raw.commit_parser in _known_commit_parsers
+        #     else "angular"
+        # )
+
         self = cls(
             repo_dir=raw.repo_dir,
             commit_parser=commit_parser,
@@ -651,10 +687,16 @@ class RuntimeContext:
             version_declarations=tuple(version_declarations),
             hvcs_client=hvcs_client,
             changelog_file=changelog_file,
+            changelog_mode=raw.changelog.mode,
+            changelog_insertion_flag=raw.changelog.insertion_flag,
             assets=raw.assets,
             commit_author=commit_author,
             commit_message=raw.commit_message,
             changelog_excluded_commit_patterns=changelog_excluded_commit_patterns,
+            # TODO: change when we have other styles per parser
+            # changelog_style=changelog_style,
+            changelog_style="angular",
+            changelog_output_format=raw.changelog.default_templates.output_format,
             prerelease=branch_config.prerelease,
             ignore_token_for_push=raw.remote.ignore_token_for_push,
             template_dir=template_dir,

semantic_release/cli/const.py

@@ -1 +1,5 @@
 DEFAULT_CONFIG_FILE = "pyproject.toml"
+DEFAULT_RELEASE_NOTES_TPL_FILE = "release_notes.md.j2"
+DEFAULT_CHANGELOG_NAME_STEM = "CHANGELOG"
+
+JINJA2_EXTENSION = ".j2"

semantic_release/cli/github_actions_output.py

@@ -12,7 +12,9 @@ class VersionGitHubActionsOutput:
     OUTPUT_ENV_VAR = "GITHUB_OUTPUT"
 
     def __init__(
-        self, released: bool | None = None, version: Version | None = None
+        self,
+        released: bool | None = None,
+        version: Version | None = None,
     ) -> None:
         self._released = released
         self._version = version
@@ -29,9 +31,7 @@ class VersionGitHubActionsOutput:
 
     @property
     def version(self) -> Version | None:
-        if self._version is None:
-            return None
-        return self._version
+        return self._version if self._version is not None else None
 
     @version.setter
     def version(self, value: Version) -> None:
@@ -41,9 +41,11 @@ class VersionGitHubActionsOutput:
 
     @property
     def tag(self) -> str | None:
-        if self._version is None:
-            return None
-        return self._version.as_tag()
+        return self.version.as_tag() if self.version is not None else None
+
+    @property
+    def is_prerelease(self) -> bool | None:
+        return self.version.is_prerelease if self.version is not None else None
 
     def to_output_text(self) -> str:
         missing = set()
@@ -61,6 +63,7 @@ class VersionGitHubActionsOutput:
             "released": str(self.released).lower(),
             "version": str(self.version),
             "tag": self.tag,
+            "is_prerelease": str(self.is_prerelease).lower(),
         }
 
         return str.join("", [f"{key}={value!s}\n" for key, value in outputs.items()])

semantic_release/commit_parser/angular.py

@@ -27,11 +27,19 @@ def _logged_parse_error(commit: Commit, error: str) -> ParseError:
     return ParseError(commit, error=error)
 
 
+# TODO: Remove from here, allow for user customization instead via options
 # types with long names in changelog
 LONG_TYPE_NAMES = {
-    "feat": "feature",
+    "build": "build system",
+    "ci": "continuous integration",
+    "chore": "chores",
     "docs": "documentation",
-    "perf": "performance",
+    "feat": "features",
+    "fix": "fixes",
+    "perf": "performance improvements",
+    "refactor": "refactoring",
+    "style": "code style",
+    "test": "testing",
 }
 
 
@@ -82,7 +90,7 @@ class AngularCommitParser(CommitParser[ParseResult, AngularParserOptions]):
     def get_default_options() -> AngularParserOptions:
         return AngularParserOptions()
 
-    # Maybe this can be cached as an optimisation, similar to how
+    # Maybe this can be cached as an optimization, similar to how
     # mypy/pytest use their own caching directories, for very large commit
     # histories?
     # The problem is the cache likely won't be present in CI environments

semantic_release/data/templates/angular/md/.changelog_header.md.j2

@@ -0,0 +1,9 @@
+# CHANGELOG
+
+{%    if ctx.changelog_mode == "update"
+%}{#  # IMPORTANT: add insertion flag for next version update
+#}{{
+        insertion_flag ~ "\n"
+
+}}{%  endif
+%}

semantic_release/data/templates/angular/md/.changelog_init.md.j2

@@ -0,0 +1,22 @@
+{#
+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
+
+#}{#
+   #    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.
+#}{%    for release in context.history.released.values()
+%}{{      "\n"
+}}{%      include ".versioned_changes.md.j2"
+-%}{{     "\n"
+}}{%    endfor
+%}

semantic_release/data/templates/angular/md/.changelog_update.md.j2

@@ -0,0 +1,62 @@
+{#
+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
+%}{#
+   #    Any Unreleased Details (uncommon)
+#}{%    include ".unreleased_changes.md.j2"
+-%}{#
+   #    Latest Release Details
+#}{%    for release in new_releases
+%}{#      # Check if the release version is already in the changelog and if not, add it
+#}{%      if "# " ~ release.version.as_semver_tag() ~ " " not in changelog_parts[1]
+%}{{        "\n"
+}}{%        include ".versioned_changes.md.j2"
+-%}{{       "\n"
+}}{%      endif
+%}{%    endfor
+%}{#
+   #    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
+%}

semantic_release/data/templates/angular/md/.changes.md.j2

@@ -0,0 +1,16 @@
+{#
+#}{%  for type_, commits in commit_objects
+%}{{
+        "\n### %s\n" | format(type_ | title)
+
+}}{%    for commit in commits
+%}{{
+          "\n* %s ([`%s`](%s))\n" | format(
+              commit.message.rstrip(),
+              commit.short_hash,
+              commit.hexsha | commit_hash_url,
+          )
+
+}}{%    endfor
+%}{%  endfor
+%}

semantic_release/data/templates/angular/md/.unreleased_changes.md.j2

@@ -0,0 +1,7 @@
+{%    if unreleased_commits | length > 0
+%}{{    "\n## Unreleased\n"
+}}{%    set commit_objects = unreleased_commits
+%}{%    include ".changes.md.j2"
+-%}{{   "\n"
+}}{%  endif
+%}

semantic_release/data/templates/angular/md/.versioned_changes.md.j2

@@ -0,0 +1,14 @@
+{#
+
+## vX.X.X (YYYY-MMM-DD)
+
+#}{{
+
+      "## %s (%s)\n" | format(
+        release.version.as_semver_tag(),
+        release.tagged_date.strftime("%Y-%m-%d")
+      )
+
+}}{%  set commit_objects = release["elements"] | dictsort
+%}{%  include ".changes.md.j2"
+-%}

semantic_release/data/templates/angular/md/CHANGELOG.md.j2

@@ -0,0 +1,24 @@
+{#
+    This changelog template controls which changelog creation occurs
+    based on which mode is provided.
+
+    Modes:
+        - init: Initialize a full changelog from scratch
+        - update: Insert new version details where the placeholder exists in the current changelog
+
+#}{%  set insertion_flag = ctx.changelog_insertion_flag
+%}{%  set unreleased_commits = ctx.history.unreleased | dictsort
+%}{#
+#}{%  if ctx.changelog_mode == "init"
+%}{%    include ".changelog_init.md.j2"
+%}{#
+#}{%  elif ctx.changelog_mode == "update"
+%}{%    set prev_changelog_file = ctx.prev_changelog_file
+%}{%    set new_releases = []
+%}{%    if ctx.history.released.values() | length > 0
+%}{%      set new_releases = [ctx.history.released.values() | first]
+%}{%    endif
+%}{%    include ".changelog_update.md.j2"
+%}{#
+#}{%  endif
+%}

semantic_release/data/templates/angular/release_notes.md.j2

@@ -0,0 +1 @@
+{% include "./md/.versioned_changes.md.j2" %}

semantic_release/errors.py

@@ -8,6 +8,10 @@ class SemanticReleaseBaseError(Exception):
     """
 
 
+class InternalError(SemanticReleaseBaseError):
+    """Raised when an internal error occurs, which should never happen"""
+
+
 class InvalidConfiguration(SemanticReleaseBaseError):
     """Raised when configuration is deemed invalid"""
 

semantic_release/data/templates/CHANGELOG.md.j2

@@ -1,21 +0,0 @@
-# CHANGELOG
-{% if context.history.unreleased | length > 0 -%}
-{# UNRELEASED #}
-## Unreleased
-{% for type_, commits in context.history.unreleased | dictsort %}
-### {{ type_ | capitalize }}
-{% for commit in commits %}{% if type_ != "unknown" %}
-* {{ commit.message.rstrip() }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
-{% else %}
-* {{ commit.message.rstrip() }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
-{% endif %}{% endfor %}{% endfor %}{% endif -%}
-{% for version, release in context.history.released.items() -%}
-{# RELEASED #}
-## {{ version.as_semver_tag() }} ({{ release.tagged_date.strftime("%Y-%m-%d") }})
-{% for type_, commits in release["elements"] | dictsort %}
-### {{ type_ | capitalize }}
-{% for commit in commits %}{% if type_ != "unknown" %}
-* {{ commit.message.rstrip() }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
-{% else %}
-* {{ commit.message.rstrip() }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
-{% endif %}{% endfor %}{% endfor %}{% endfor %}

semantic_release/data/templates/release_notes.md.j2

@@ -1,8 +0,0 @@
-# {{ version.as_tag() }} ({{ release.tagged_date.strftime("%Y-%m-%d") }})
-{% for type_, commits in release["elements"] | dictsort %}
-## {{ type_ | capitalize }}
-{% for commit in commits %}{% if type_ != "unknown" %}
-* {{ commit.message.rstrip() }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
-{% else %}
-* {{ commit.message.rstrip() }} ([`{{ commit.short_hash }}`]({{ commit.hexsha | commit_hash_url }}))
-{% endif %}{% endfor %}{% endfor %}