python-semantic-release 9.10.1__tar.gz → 9.11.1__tar.gz

{python_semantic_release-9.10.1/python_semantic_release.egg-info → python_semantic_release-9.11.1}/PKG-INFO

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

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/docs/automatic-releases/github-actions.rst

@@ -337,7 +337,7 @@ before the :ref:`version <cmd-version>` subcommand.
 
   .. code:: yaml
 
-    - uses: python-semantic-release/python-semantic-release@v9.10.1
+    - uses: python-semantic-release/python-semantic-release@v9.11.1
       with:
         root_options: "-vv --noop"
 
@@ -684,7 +684,7 @@ to the GitHub Release Assets as well.
           - name: Action | Semantic Version Release
             id: release
             # Adjust tag with desired version if applicable.
-            uses: python-semantic-release/python-semantic-release@v9.10.1
+            uses: python-semantic-release/python-semantic-release@v9.11.1
             with:
               github_token: ${{ secrets.GITHUB_TOKEN }}
               git_committer_name: "github-actions"
@@ -744,7 +744,7 @@ The equivalent GitHub Action configuration would be:
 
   - name: Action | Semantic Version Release
     # Adjust tag with desired version if applicable.
-    uses: python-semantic-release/python-semantic-release@v9.10.1
+    uses: python-semantic-release/python-semantic-release@v9.11.1
     with:
       github_token: ${{ secrets.GITHUB_TOKEN }}
       force: patch
@@ -772,13 +772,13 @@ Publish Action.
 .. code:: yaml
 
    - name: Release Project 1
-     uses: python-semantic-release/python-semantic-release@v9.10.1
+     uses: python-semantic-release/python-semantic-release@v9.11.1
      with:
        directory: ./project1
        github_token: ${{ secrets.GITHUB_TOKEN }}
 
    - name: Release Project 2
-     uses: python-semantic-release/python-semantic-release@v9.10.1
+     uses: python-semantic-release/python-semantic-release@v9.11.1
      with:
        directory: ./project2
        github_token: ${{ secrets.GITHUB_TOKEN }}

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/docs/changelog_templates.rst

@@ -36,8 +36,48 @@ the :ref:`--no-changelog <cmd-version-option-changelog>` command-line option.
 Using the Default Changelog
 ---------------------------
 
-There are 2 modes that change the output method of the default changelog and the mode
-is determined by the :ref:`changelog.mode <config-changelog-mode>` setting.
+If you don't provide any custom templates in the
+:ref:`changelog.template_dir <config-changelog-template_dir>`, the default changelog
+templates will be used to render the changelog.
+
+PSR provides two default changelog output formats:
+
+1.  Markdown (``.md``), *default*
+
+2.  reStructuredText (``.rst``), *available since v9.11.0*
+
+Both formats are kept in sync with one another to display the equivalent information
+in the respective format. The default changelog template is located in the
+``data/templates/`` directory within the PSR package. The templates are written in
+modular style (ie. multiple files) and during the render proccess are ultimately
+combined together to render the final changelog output. The rendering start point
+is the ``CHANGELOG.{FORMAT_EXT}.j2`` underneath the respective format directory.
+
+PSR provides a few configuration options to customize the default changelog output
+and can be found under the
+:ref:`changelog.default_templates <config-changelog-default_templates>` section
+as well as some common configuration options under the :ref:`config-changelog`
+section.
+
+To toggle the output format, you only need to set the
+:ref:`changelog.default_templates.changelog_file <config-changelog-default_templates-changelog_file>`
+file name to include the desired file extension (``.md`` or ``.rst``). If you would
+like a different extension for the resulting changelog file, but would like
+to still have control over the template format, you can set the
+:ref:`changelog.default_templates.output_format <config-changelog-default_templates-output_format>`
+configuration setting to the desired format.
+
+A common and *highly-recommended* configuration option is the
+:ref:`changelog.exclude_commit_patterns <config-changelog-exclude_commit_patterns>`
+setting which allows the user to define regular expressions that will exclude commits
+from the changelog output. This is useful to filter out change messages that are not
+relevant to your external consumers (ex. ``ci`` and ``test`` in the angular commit
+convention) and only include the important changes that impact the consumer of your
+software.
+
+Another important configuration option is the :ref:`changelog.mode <config-changelog-mode>`
+setting which determines the behavior of the changelog generation. There are 2
+modes that available that described in detail below.
 
 1.  :ref:`changelog-templates-default_changelog-init` when ``mode = "init"``.
 
@@ -153,6 +193,60 @@ information will be inserted after the insertion flag.
     - Initial Release
 
 
+.. _changelog-templates-default_changelog-examples:
+
+Configuration Examples
+^^^^^^^^^^^^^^^^^^^^^^
+
+1.  Goal: Configure an updating reStructuredText changelog with a custom insertion
+    flag within ``pyproject.toml``.
+
+    .. code:: toml
+
+        [tool.semantic_release.changelog]
+        mode = "update"
+        insertion_flag = "..\n    All versions below are listed in reverse chronological order"
+
+        [tool.semantic_release.changelog.default_templates]
+        changelog_file = "CHANGELOG.rst"
+        output_format = "rst"  # optional because of the file extension
+
+2.  Goal: Configure an updating Markdown changelog with custom file name and default
+    insertion flag within a separate config file ``releaserc.json``.
+
+    .. code:: json
+
+        {
+          "semantic_release": {
+            "changelog": {
+              "mode": "update",
+              "default_templates": {
+                "changelog_file": "docs/HISTORY",
+                "output_format": "md"
+              }
+            }
+          }
+        }
+
+3.  Goal: Configure an initializing reStructuredText changelog with filtered angular
+    commits patterns and merge commits within a custom config file ``releaserc.toml``.
+
+    .. code:: toml
+
+        [semantic_release.changelog]
+        mode = "init"
+        default_templates = { changelog_file = "docs/CHANGELOG.rst" }
+        exclude_commit_patterns = [
+          '''chore(?:\([^)]*?\))?: .+''',
+          '''ci(?:\([^)]*?\))?: .+''',
+          '''refactor(?:\([^)]*?\))?: .+''',
+          '''style(?:\([^)]*?\))?: .+''',
+          '''test(?:\([^)]*?\))?: .+''',
+          '''build\((?!deps\): .+)''',
+          '''Merged? .*''',
+        ]
+
+
 .. _changelog-templates-default_release_notes:
 
 Using the Default Release Notes
@@ -493,6 +587,24 @@ arguments are passed in parentheses like normal function calls.
 
 The filters provided vary based on the VCS configured and available features:
 
+* ``convert_md_to_rst (Callable[[MdStr], RstStr])``: given a markdown string, convert it to
+  reStructuredText format. This filter is useful when building a reStructuredText changelog
+  but your commit messages are in markdown format. It is utilized by the default RST changelog
+  template. It is limited in its ability to convert all markdown to reStructuredText, but it
+  handles most common cases (bold, italics, inline-raw, etc.) within commit messages.
+
+  *Introduced in v9.11.0.*
+
+  **Example Usage:**
+
+  .. code:: jinja
+
+      {{  "\n* %s (`%s`_)\n" | format(
+            commit.message.rstrip() | convert_md_to_rst,
+            commit.short_hash,
+          )
+      }}
+
 * ``create_server_url (Callable[[PathStr, AuthStr | None, QueryStr | None, FragmentStr | None], UrlStr])``:
   when given a path, prepend the configured vcs server host and url scheme.  Optionally you
   can provide, a auth string, a query string or a url fragment to be normalized into the
@@ -632,6 +744,7 @@ Availability of the documented filters can be found in the table below:
 ======================  =========  =====  ======  ======
 **filter - hvcs_type**  bitbucket  gitea  github  gitlab
 ======================  =========  =====  ======  ======
+convert_md_to_rst          ✅       ✅      ✅      ✅
 create_server_url          ✅       ✅      ✅      ✅
 create_repo_url            ✅       ✅      ✅      ✅
 commit_hash_url            ✅       ✅      ✅      ✅
@@ -830,6 +943,11 @@ existing changelog, follow these steps:
     step 2. The insertion flag should be placed in the location above where you would like
     the new release information to be inserted.
 
+.. note::
+    If you are trying to convert an existing changelog to a new format, you will need to do
+    most of the conversion manually (or rebuild via init and modify) and make sure to include
+    your insertion flag into the format of the new changelog.
+
 **Prior to v9.10.0**
 
 If you have an existing changelog that you would like to preserve, you will need to

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/docs/configuration.rst

@@ -295,12 +295,23 @@ This section outlines the configuration options available that modify changelog
 ``changelog_file``
 ******************
 
+.. warning::
+    *Deprecated in v9.11.0.* This setting has been moved to
+    :ref:`changelog.default_templates.changelog_file <config-changelog-default_templates-changelog_file>`
+    for a more logical grouping. This setting will be removed in a future major release.
+
 **Type:** ``str``
 
 Specify the name of the changelog file that will be created. This file will be created
 or overwritten (if it previously exists) with the rendered default template included
 with Python Semantic Release.
 
+Depending on the file extension of this setting, the changelog will be rendered in the
+format designated by the extension. PSR, as of v9.11.0, provides a default changelog template
+in both Markdown (``.md``) and reStructuredText (``.rst``) formats. If the file extension is
+not recognized, the changelog will be rendered in Markdown format, unless the
+:ref:`config-changelog-default_templates-output_format` setting is set.
+
 If you are using the ``template_dir`` setting for providing customized templates,
 this setting is not used. See :ref:`config-changelog-template_dir` for more information.
 
@@ -325,6 +336,32 @@ this setting is not used. See :ref:`config-changelog-template_dir` for more info
 
 ----
 
+.. _config-changelog-default_templates-changelog_file:
+
+``changelog_file``
+''''''''''''''''''
+
+*Introduced in v9.11.0.*
+
+**Type:** ``str``
+
+Specify the name of the changelog file that will be created. This file will be created
+or overwritten (if it previously exists) with the rendered default template included
+with Python Semantic Release.
+
+Depending on the file extension of this setting, the changelog will be rendered in the
+format designated by the extension. PSR, as of v9.11.0, provides a default changelog template
+in both Markdown (``.md``) and reStructuredText (``.rst``) formats. If the file extension is
+not recognized, the changelog will be rendered in Markdown format, unless the
+:ref:`config-changelog-default_templates-output_format` setting is set.
+
+If you are using the ``template_dir`` setting for providing customized templates,
+this setting is not used. See :ref:`config-changelog-template_dir` for more information.
+
+**Default:** ``"CHANGELOG.md"``
+
+----
+
 .. _config-changelog-default_templates-output_format:
 
 ``output_format``
@@ -332,14 +369,23 @@ this setting is not used. See :ref:`config-changelog-template_dir` for more info
 
 *Introduced in v9.10.0*
 
-**Type:** ``Literal["md"]``
+**Type:** ``Literal["md", "rst"]``
 
 This setting is used to specify the output format the default changelog template
-will use when rendering the changelog. Currently, the only supported format is
-``md`` for Markdown.
+will use when rendering the changelog. PSR supports both Markdown (``md``) and
+reStructuredText (``rst``) formats.
+
+This setting will take presendence over the file extension of the
+:ref:`config-changelog-default_templates-changelog_file` setting. If this setting is
+omitted, the file extension of the :ref:`config-changelog-default_templates-changelog_file`
+setting will be used to determine the output format. If the file extension is not recognized,
+the output format will default to Markdown.
 
 **Default:** ``"md"``
 
+.. seealso::
+   - :ref:`config-changelog-default_templates-changelog_file`
+
 ----
 
 .. _config-changelog-environment:
@@ -625,9 +671,20 @@ for future version insertions.
 
 If you modify this value in your config, you will need to manually update any saved changelog
 file to match the new insertion flag if you use the ``update`` mode.  In ``init`` mode, the
-changelog file will be overwritten with the new insertion flag as normal.
+changelog file will be overwritten as normal.
+
+In v9.11.0, the ``insertion_flag`` default value became more dynamic with the introduction of
+an reStructuredText template. The default value will be set depending on the
+:ref:`config-changelog-default_templates-output_format` setting. The default flag values are:
+
+==================  =========================
+Output Format       Default Insertion Flag
+==================  =========================
+Markdown (``md``)   ``<!-- version list -->``
+reStructuredText    ``..\n    version list``
+==================  =========================
 
-**Default:** ``<!-- version list -->``
+**Default:** various, see above
 
 ----
 

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-semantic-release"
-version = "9.10.1"
+version = "9.11.1"
 description = "Automatic Semantic Versioning for Python projects"
 requires-python = ">=3.8"
 license = { text = "MIT" }

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1/python_semantic_release.egg-info}/PKG-INFO

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

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/python_semantic_release.egg-info/SOURCES.txt

@@ -11,6 +11,14 @@ pyproject.toml
 ./semantic_release/data/templates/angular/md/.unreleased_changes.md.j2
 ./semantic_release/data/templates/angular/md/.versioned_changes.md.j2
 ./semantic_release/data/templates/angular/md/CHANGELOG.md.j2
+./semantic_release/data/templates/angular/rst/.changelog_header.rst.j2
+./semantic_release/data/templates/angular/rst/.changelog_init.rst.j2
+./semantic_release/data/templates/angular/rst/.changelog_update.rst.j2
+./semantic_release/data/templates/angular/rst/.changes.rst.j2
+./semantic_release/data/templates/angular/rst/.macros.rst.j2
+./semantic_release/data/templates/angular/rst/.unreleased_changes.rst.j2
+./semantic_release/data/templates/angular/rst/.versioned_changes.rst.j2
+./semantic_release/data/templates/angular/rst/CHANGELOG.rst.j2
 docs/Makefile
 docs/algorithm.rst
 docs/changelog_templates.rst
@@ -77,6 +85,14 @@ semantic_release/data/templates/angular/md/.changes.md.j2
 semantic_release/data/templates/angular/md/.unreleased_changes.md.j2
 semantic_release/data/templates/angular/md/.versioned_changes.md.j2
 semantic_release/data/templates/angular/md/CHANGELOG.md.j2
+semantic_release/data/templates/angular/rst/.changelog_header.rst.j2
+semantic_release/data/templates/angular/rst/.changelog_init.rst.j2
+semantic_release/data/templates/angular/rst/.changelog_update.rst.j2
+semantic_release/data/templates/angular/rst/.changes.rst.j2
+semantic_release/data/templates/angular/rst/.macros.rst.j2
+semantic_release/data/templates/angular/rst/.unreleased_changes.rst.j2
+semantic_release/data/templates/angular/rst/.versioned_changes.rst.j2
+semantic_release/data/templates/angular/rst/CHANGELOG.rst.j2
 semantic_release/hvcs/__init__.py
 semantic_release/hvcs/_base.py
 semantic_release/hvcs/bitbucket.py

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/semantic_release/__init__.py

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

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/semantic_release/changelog/context.py

@@ -5,6 +5,7 @@ import os
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
+from re import compile as regexp
 from typing import TYPE_CHECKING, Any, Callable, Literal
 
 if TYPE_CHECKING:
@@ -77,7 +78,11 @@ def make_changelog_context(
         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(), read_file),
+        filters=(
+            *hvcs_client.get_changelog_context_filters(),
+            read_file,
+            convert_md_to_rst,
+        ),
     )
 
 
@@ -88,3 +93,22 @@ def read_file(filepath: str) -> str:
     except FileNotFoundError as err:
         logging.warning(err)
         return ""
+
+
+def convert_md_to_rst(md_content: str) -> str:
+    rst_content = md_content
+    replacements = {
+        # Replace markdown doubleunder bold with rst bold
+        "bold-inline": (regexp(r"(?<=\s)__(.+?)__(?=\s|$)"), r"**\1**"),
+        # Replace markdown italics with rst italics
+        "italic-inline": (regexp(r"(?<=\s)_([^_].+?[^_])_(?=\s|$)"), r"*\1*"),
+        # Replace markdown bullets with rst bullets
+        "bullets": (regexp(r"^(\s*)-(\s)"), r"\1*\2"),
+        # Replace markdown inline raw content with rst inline raw content
+        "raw-inline": (regexp(r"(?<=\s)(`[^`]+`)(?![`_])(?=\s|$)"), r"`\1`"),
+    }
+
+    for pattern, replacement in replacements.values():
+        rst_content = pattern.sub(replacement, rst_content)
+
+    return rst_content

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/semantic_release/changelog/template.py

@@ -92,7 +92,6 @@ class ComplexDirectorySandboxedEnvironment(SandboxedEnvironment):
         return str(PurePosixPath(parent).parent / template)
 
 
-# pylint: disable=redefined-outer-name
 def recursive_render(
     template_dir: Path,
     environment: Environment,
@@ -103,13 +102,8 @@ def recursive_render(
         (Path(root), file)
         for root, _, files in os.walk(template_dir)
         for file in files
-        # we slice relpath.parts[1:] to allow the top-level
-        # template folder to have a dot prefix.
-        # e.g. to permit ".github/psr-templates" to contain the templates,
-        # rather than enforcing a top-level, non-hidden directory
         if not any(
-            elem.startswith(".")
-            for elem in Path(root).relative_to(template_dir).parts[1:]
+            elem.startswith(".") for elem in Path(root).relative_to(template_dir).parts
         )
         and not file.startswith(".")
     ):

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/semantic_release/cli/config.py

@@ -99,7 +99,8 @@ class ChangelogOutputFormat(str, Enum):
     """Supported changelog output formats when using the default templates."""
 
     MARKDOWN = "md"
-    # RESTRUCTURED_TEXT = "rst"
+    RESTRUCTURED_TEXT = "rst"
+    NONE = ""
 
 
 class ChangelogEnvironmentConfig(BaseModel):
@@ -120,23 +121,97 @@ class ChangelogEnvironmentConfig(BaseModel):
 
 
 class DefaultChangelogTemplatesConfig(BaseModel):
-    # TODO: BREAKING CHANGE v10
-    # changelog_file: str = "CHANGELOG.md"
-    output_format: ChangelogOutputFormat = ChangelogOutputFormat.MARKDOWN
+    changelog_file: str = "CHANGELOG.md"
+    output_format: ChangelogOutputFormat = ChangelogOutputFormat.NONE
+
+    @model_validator(mode="after")
+    def interpret_output_format(self) -> Self:
+        # Set the output format value when no user input is given
+        if self.output_format == ChangelogOutputFormat.NONE:
+            try:
+                # Note: If the user gave no extension, force '.' so enumeration fails,
+                # and defaults to markdown
+                # Otherwise normal files with extensions will just look for the extension support
+                self.output_format = ChangelogOutputFormat(
+                    Path(self.changelog_file).suffix.lstrip(".") or "."
+                )
+            except ValueError:
+                self.output_format = ChangelogOutputFormat.MARKDOWN
+
+        return self
 
 
 class ChangelogConfig(BaseModel):
     # TODO: BREAKING CHANGE v10, move to DefaultChangelogTemplatesConfig
-    changelog_file: str = "CHANGELOG.md"
+    changelog_file: str = ""
+    """Deprecated! Moved to 'default_templates.changelog_file'"""
+
     default_templates: DefaultChangelogTemplatesConfig = (
-        DefaultChangelogTemplatesConfig()
+        DefaultChangelogTemplatesConfig(output_format=ChangelogOutputFormat.NONE)
     )
     environment: ChangelogEnvironmentConfig = ChangelogEnvironmentConfig()
     exclude_commit_patterns: Tuple[str, ...] = ()
     mode: ChangelogMode = ChangelogMode.INIT
-    insertion_flag: str = "<!-- version list -->"
+    insertion_flag: str = ""
     template_dir: str = "templates"
 
+    @field_validator("changelog_file", mode="after")
+    @classmethod
+    def changelog_file_deprecation_warning(cls, val: str) -> str:
+        log.warning(
+            str.join(
+                " ",
+                [
+                    "The 'changelog.changelog_file' configuration option is moving to 'changelog.default_templates.changelog_file'.",
+                    "Please update your configuration as the compatibility will break in v10.",
+                ],
+            )
+        )
+        return val
+
+    @model_validator(mode="after")
+    def move_changelog_file(self) -> Self:
+        # TODO: Remove this method in v10
+        if not self.changelog_file:
+            return self
+
+        if self.changelog_file == self.default_templates.changelog_file:
+            return self
+
+        # Re-evaluate now that we are passing the changelog_file option down to default_templates
+        # and only reset the output_format if it was not already set by the user
+        self.default_templates = DefaultChangelogTemplatesConfig.model_validate(
+            {
+                **self.default_templates.model_dump(),
+                "changelog_file": self.changelog_file,
+                "output_format": (
+                    self.default_templates.output_format
+                    if self.default_templates.output_format
+                    != ChangelogOutputFormat.MARKDOWN
+                    else ChangelogOutputFormat.NONE
+                ),
+            }
+        )
+
+        return self
+
+    @model_validator(mode="after")
+    def load_default_insertion_flag_on_missing(self) -> Self:
+        # Set the insertion flag value when no user input is given
+        if not self.insertion_flag:
+            defaults = {
+                ChangelogOutputFormat.MARKDOWN: "<!-- version list -->",
+                ChangelogOutputFormat.RESTRUCTURED_TEXT: f"..{os.linesep}    version list",
+            }
+            try:
+                self.insertion_flag = defaults[self.default_templates.output_format]
+            except KeyError as err:
+                raise ValueError(
+                    "changelog.default_templates.output_format cannot be None"
+                ) from err
+
+        return self
+
 
 class BranchConfig(BaseModel):
     match: str = "(main|master)"
@@ -620,7 +695,10 @@ class RuntimeContext:
         # which means it returns a relative path. So we force absolute to ensure path is complete
         # for the next check of path matching
         changelog_file = (
-            Path(raw.changelog.changelog_file).expanduser().resolve().absolute()
+            Path(raw.changelog.default_templates.changelog_file)
+            .expanduser()
+            .resolve()
+            .absolute()
         )
 
         # Prevent path traversal attacks

{python_semantic_release-9.10.1 → python_semantic_release-9.11.1}/semantic_release/data/templates/angular/md/.changelog_update.md.j2

@@ -46,7 +46,7 @@ This Update changelog template uses the following logic:
 %}{#      # 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"
+}}{%-       include ".versioned_changes.md.j2"
 -%}{{       "\n"
 }}{%      endif
 %}{%    endfor

python_semantic_release-9.11.1/semantic_release/data/templates/angular/rst/.changelog_header.rst.j2

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

python_semantic_release-9.11.1/semantic_release/data/templates/angular/rst/.changelog_init.rst.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.rst.j2"
+-%}{#
+   #   Any Unreleased Details (uncommon)
+#}{%   include ".unreleased_changes.rst.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.rst.j2"
+-%}{{      "\n"
+}}{%   endfor
+%}