introduce snippet based changelog

Author: brainelectronics

.github/workflows/release.yml

@@ -26,10 +26,15 @@ jobs:
       - name: Install build dependencies
         run: |
           if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
+      - name: Update changelog with snippets
+        run: |
+          changelog-generator \
+            changelog changelog.md \
+            --snippets=.snippets
       - name: Build package
         run: |
           changelog2version \
-            --changelog_file changelog.md \
+            --changelog_file changelog.md.new \
             --version_file be_upy_blink/version.py \
             --version_file_type py \
             --debug
@@ -49,7 +54,7 @@ jobs:
           # note you'll typically need to create a personal access token
           # with permissions to create releases in the other repo
           # or you set the "contents" permissions to "write" as in this example
-          changelog-path: changelog.md
+          changelog-path: changelog.md.new
           tag-name-prefix: ''
           tag-name-extension: ''
           release-name-prefix: ''

.github/workflows/test-release.yaml

@@ -23,10 +23,15 @@ jobs:
       - name: Install build dependencies
         run: |
           if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi
+      - name: Update changelog with snippets
+        run: |
+          changelog-generator \
+            changelog changelog.md \
+            --snippets=.snippets
       - name: Build package
         run: |
           changelog2version \
-            --changelog_file changelog.md \
+            --changelog_file changelog.md.new \
             --version_file be_upy_blink/version.py \
             --version_file_type py \
             --additional_version_info="-rc${{ github.run_number }}.dev${{ github.event.number }}" \
@@ -60,7 +65,7 @@ jobs:
           # note you'll typically need to create a personal access token
           # with permissions to create releases in the other repo
           # or you set the "contents" permissions to "write" as in this example
-          changelog-path: changelog.md
+          changelog-path: changelog.md.new
           tag-name-prefix: ''
           tag-name-extension: '-rc${{ github.run_number }}.dev${{ github.event.number }}'
           release-name-prefix: ''

.github/workflows/test.yml

@@ -40,13 +40,18 @@ jobs:
       - name: Lint with yamllint
         run: |
           yamllint .
+      - name: Update changelog with snippets
+        run: |
+          changelog-generator \
+            changelog changelog.md \
+            --snippets=.snippets
       - name: Validate package version file
         # the package version file has to be always up to date as mip is using
         # the file directly from the repo. On a PyPi package the version file
         # is updated and then packed
         run: |
           changelog2version \
-            --changelog_file changelog.md \
+            --changelog_file changelog.md.new \
             --version_file be_upy_blink/version.py \
             --version_file_type py \
             --validate \
@@ -55,7 +60,7 @@ jobs:
         run: |
           upy-package \
             --setup_file setup.py \
-            --package_changelog_file changelog.md \
+            --package_changelog_file changelog.md.new \
             --package_file package.json \
             --validate
         # use --ignore-version to skip version validation

.gitignore

@@ -1,3 +1,6 @@
+# snippets2changelog specific
+changelog.md.new
+
 # custom, package specific ignores
 .DS_Store
 .DS_Store?

.snippets/22.md

@@ -0,0 +1,12 @@
+## Use changelog snippets
+<!--
+type: feature
+scope: all
+affected: all
+-->
+
+This change replaces the modifications and extensions of a changelog by
+generating the changelog with all its entries and versions based on changelog
+snippets like this one.
+
+This closes [#22](https://github.com/brainelectronics/micropython-package-template/issues/22)

docs/CONTRIBUTING.md

@@ -107,29 +107,49 @@ pre-commit run --all-files
 The changelog format is based on [Keep a Changelog][ref-keep-a-changelog], and
 this project adheres to [Semantic Versioning][ref-semantic-versioning].
 
-Please add a changelog entry for every PR you contribute. The versions are
-seperated into `MAJOR.MINOR.PATCH`:
-
-- Increment the major version by 1 in case you created a breaking, non
-backwards compatible change which requires the user to perform additional
-tasks, adopt his currently running code or in general can't be used as is anymore.
-- Increment the minor version by 1 on new "features" which can be used or are
-optional, but in either case do not require any changes by the user to keep
-the system running after upgrading.
-- Increment the patch version by 1 on bugfixes which fix an issue but can be
-used out of the box, like features, without any changes by the user. In some
-cases bugfixes can be breaking changes of course.
-
-Please add the date the change has been made as well to the changelog
-following the format `## [MAJOR.MINOR.PATCH] - YYYY-MM-DD`. It is not
-necessary to keep this date up to date, it is just used as meta data.
+### General
+
+Please add a changelog snippet for every PR you contribute. The changes are
+categorised into:
+
+- `Bugfixes` fix an issue which can be used out of the box without any further
+changes required by the user. Be aware that in some cases bugfixes can be
+breaking changes.
+- `features` is used to indicate a backwards compatible change providing
+improved or extended functionalitiy. This does, as `bugfixes`, in any case
+not require any changes by the user to keep the system running after upgrading.
+- `breaking` creates a breaking, non backwards compatible change which
+requires the user to perform additional tasks, adopt his currently running
+code or in general can't be used as is anymore.
 
 The changelog entry shall be short but meaningful and can of course contain
 links and references to other issues or PRs. New lines are only allowed for a
 new bulletpoint entry. Usage examples or other code snippets should be placed
 in the code documentation, README or the docs folder.
 
-### General
+### Creation
+
+To create a new changelog snippet use the CLI tool with its simple interface.
+Use the issue number, in this example `22.md`, as the snippet name. The
+extension shall always be `.md`.
+
+```bash
+changelog-generator create .snippets/22.md
+```
+
+The tool will create a basic snippet which can and should be extended with a
+detailed description of the change after the file creation.
+
+### Generation
+
+Commit the changes and the snippet file and run the following command to create
+a changelog with the latest snippet included
+
+```bash
+changelog-generator changelog changelog.md --snippets=.snippets
+```
+
+### Version file
 
 The package version file, located at `<PACKAGE_NAME>/version.py` contains the
 latest changelog version.

requirements-deploy.txt

@@ -3,3 +3,4 @@
 # # to upload package to PyPi or other package hosts
 twine>=4.0.1,<5
 changelog2version>=0.5.0,<1
+snippets2changelog>=1.0.3,<2