Merge pull request #23 from brainelectronics/feature/use-changelog-snippets

Use changelog snippets

Author: brainelectronics

.github/workflows/release.yml

@@ -18,14 +18,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          # all history is needed to crawl it properly
+          fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - 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 \
+            --in-place
       - name: Build package
         run: |
           changelog2version \

.github/workflows/test-release.yaml

@@ -15,14 +15,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          # all history is needed to crawl it properly
+          fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - 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 \
+            --in-place
       - name: Build package
         run: |
           changelog2version \

.github/workflows/test.yml

@@ -26,11 +26,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          # all history is needed to crawl it properly
+          fetch-depth: 0
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - name: Install test dependencies
         run: |
           pip install -r requirements-test.txt
@@ -40,6 +43,12 @@ jobs:
       - name: Lint with yamllint
         run: |
           yamllint .
+      - name: Update changelog with snippets
+        run: |
+          changelog-generator \
+            changelog changelog.md \
+            --snippets=.snippets \
+            --in-place
       - 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

.github/workflows/unittest.yaml

@@ -14,10 +14,10 @@ jobs:
   test-and-coverage:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.11'
       - name: Execute tests
         run: |
           pip install -r requirements-test.txt

.gitignore

@@ -1,3 +1,7 @@
+# snippets2changelog specific
+changelog.md
+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)

be_upy_blink/version.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
 
-__version_info__ = ("0", "9", "0")
+__version_info__ = ("0", "10", "0")
 __version__ = '.'.join(__version_info__)

docs/CONTRIBUTING.md

@@ -107,29 +107,52 @@ 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 --in-place
+```
+
+*Be aware to restore the changelog before another run as it might generate
+version entries and version bumps multiple times otherwise.*
+
+### Version file
 
 The package version file, located at `<PACKAGE_NAME>/version.py` contains the
 latest changelog version.

package.json

@@ -14,5 +14,5 @@
         ]
     ],
     "deps": [],
-    "version": "0.9.0"
+    "version": "0.10.0"
 }

requirements-deploy.txt

@@ -1,5 +1,6 @@
 # List external packages here
 # Avoid fixed versions
 # # to upload package to PyPi or other package hosts
-twine>=4.0.1,<5
+twine>=5.1.1,<6
 changelog2version>=0.5.0,<1
+snippets2changelog>=1.1.0,<2