From 100458f98cf1683a80f6b79aa7835f392a5ee180 Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Mon, 30 Sep 2024 22:55:08 +0200 Subject: [PATCH 1/7] introduce snippet based changelog --- .github/workflows/release.yml | 9 +++-- .github/workflows/test-release.yaml | 9 +++-- .github/workflows/test.yml | 9 +++-- .gitignore | 3 ++ .snippets/22.md | 12 +++++++ docs/CONTRIBUTING.md | 54 ++++++++++++++++++++--------- requirements-deploy.txt | 1 + 7 files changed, 74 insertions(+), 23 deletions(-) create mode 100644 .snippets/22.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 93e60c8..783be3a 100644 --- a/.github/workflows/release.yml +++ b/.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: '' diff --git a/.github/workflows/test-release.yaml b/.github/workflows/test-release.yaml index 214ecc7..5d52245 100644 --- a/.github/workflows/test-release.yaml +++ b/.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: '' diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 46f6493..cce3a30 100644 --- a/.github/workflows/test.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index ada7b4e..18035e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# snippets2changelog specific +changelog.md.new + # custom, package specific ignores .DS_Store .DS_Store? diff --git a/.snippets/22.md b/.snippets/22.md new file mode 100644 index 0000000..4984b45 --- /dev/null +++ b/.snippets/22.md @@ -0,0 +1,12 @@ +## Use changelog snippets + + +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) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1e411a6..0f330bf 100755 --- a/docs/CONTRIBUTING.md +++ b/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 `/version.py` contains the latest changelog version. diff --git a/requirements-deploy.txt b/requirements-deploy.txt index 96b0350..3a10b5c 100644 --- a/requirements-deploy.txt +++ b/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 From 2f8238db8e83a81488c61dcf47f46fdd5685ed96 Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Mon, 30 Sep 2024 23:31:18 +0200 Subject: [PATCH 2/7] bump version of snippets2changelog to use --in-place flag --- .github/workflows/release.yml | 7 ++++--- .github/workflows/test-release.yaml | 7 ++++--- .github/workflows/test.yml | 7 ++++--- requirements-deploy.txt | 2 +- 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 783be3a..9d6fd54 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -30,11 +30,12 @@ jobs: run: | changelog-generator \ changelog changelog.md \ - --snippets=.snippets + --snippets=.snippets \ + --in-place - name: Build package run: | changelog2version \ - --changelog_file changelog.md.new \ + --changelog_file changelog.md \ --version_file be_upy_blink/version.py \ --version_file_type py \ --debug @@ -54,7 +55,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.new + changelog-path: changelog.md tag-name-prefix: '' tag-name-extension: '' release-name-prefix: '' diff --git a/.github/workflows/test-release.yaml b/.github/workflows/test-release.yaml index 5d52245..f99a2d9 100644 --- a/.github/workflows/test-release.yaml +++ b/.github/workflows/test-release.yaml @@ -27,11 +27,12 @@ jobs: run: | changelog-generator \ changelog changelog.md \ - --snippets=.snippets + --snippets=.snippets \ + --in-place - name: Build package run: | changelog2version \ - --changelog_file changelog.md.new \ + --changelog_file changelog.md \ --version_file be_upy_blink/version.py \ --version_file_type py \ --additional_version_info="-rc${{ github.run_number }}.dev${{ github.event.number }}" \ @@ -65,7 +66,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.new + changelog-path: changelog.md tag-name-prefix: '' tag-name-extension: '-rc${{ github.run_number }}.dev${{ github.event.number }}' release-name-prefix: '' diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index cce3a30..04aac64 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -44,14 +44,15 @@ jobs: run: | changelog-generator \ changelog changelog.md \ - --snippets=.snippets + --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 # is updated and then packed run: | changelog2version \ - --changelog_file changelog.md.new \ + --changelog_file changelog.md \ --version_file be_upy_blink/version.py \ --version_file_type py \ --validate \ @@ -60,7 +61,7 @@ jobs: run: | upy-package \ --setup_file setup.py \ - --package_changelog_file changelog.md.new \ + --package_changelog_file changelog.md \ --package_file package.json \ --validate # use --ignore-version to skip version validation diff --git a/requirements-deploy.txt b/requirements-deploy.txt index 3a10b5c..e1bfff5 100644 --- a/requirements-deploy.txt +++ b/requirements-deploy.txt @@ -3,4 +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 +snippets2changelog>=1.1.0,<2 From 5f148f078d91ba58b00cb1326e72984dff8a4dfa Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Mon, 30 Sep 2024 23:42:06 +0200 Subject: [PATCH 3/7] add snippets2changelog to test requirements --- requirements-test.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements-test.txt b/requirements-test.txt index 2ac46f6..369a64f 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -5,5 +5,6 @@ coverage>=6.4.2,<7 flake8>=5.0.0,<6 nose2>=0.12.0,<1 setup2upypackage>=0.4.0,<1 +snippets2changelog>=1.1.0,<2 pre-commit>=3.3.3,<4 yamllint>=1.29,<2 From 9eb3aad4e2f8dcbf911cec60903e7483d99baaa3 Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Mon, 30 Sep 2024 23:43:08 +0200 Subject: [PATCH 4/7] bump action versions and python version from 3.9 to 3.11 --- .github/workflows/release.yml | 9 ++++++--- .github/workflows/test-release.yaml | 9 ++++++--- .github/workflows/test.yml | 9 ++++++--- .github/workflows/unittest.yaml | 6 +++--- 4 files changed, 21 insertions(+), 12 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9d6fd54..ee159f4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,11 +18,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 build dependencies run: | if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi diff --git a/.github/workflows/test-release.yaml b/.github/workflows/test-release.yaml index f99a2d9..4683458 100644 --- a/.github/workflows/test-release.yaml +++ b/.github/workflows/test-release.yaml @@ -15,11 +15,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 build dependencies run: | if [ -f requirements-deploy.txt ]; then pip install -r requirements-deploy.txt; fi diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 04aac64..44b8602 100644 --- a/.github/workflows/test.yml +++ b/.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 diff --git a/.github/workflows/unittest.yaml b/.github/workflows/unittest.yaml index 7021275..e78db31 100644 --- a/.github/workflows/unittest.yaml +++ b/.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 From 1f2966ec232ee8ad4d7ae210d458f34777538583 Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Mon, 30 Sep 2024 23:43:37 +0200 Subject: [PATCH 5/7] add --in-place option in contribution guide line --- docs/CONTRIBUTING.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 0f330bf..90aed94 100755 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -112,7 +112,7 @@ this project adheres to [Semantic Versioning][ref-semantic-versioning]. 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 +- `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 @@ -146,9 +146,12 @@ 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 +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 `/version.py` contains the From 110dc22f61cf8fe598051ae6f22b89043231edef Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Mon, 30 Sep 2024 23:51:42 +0200 Subject: [PATCH 6/7] bump version in mip relevant package and version file --- .gitignore | 1 + be_upy_blink/version.py | 2 +- package.json | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 18035e5..1a8f6f9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ # snippets2changelog specific +changelog.md changelog.md.new # custom, package specific ignores diff --git a/be_upy_blink/version.py b/be_upy_blink/version.py index a38aa51..eecf8a9 100644 --- a/be_upy_blink/version.py +++ b/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__) diff --git a/package.json b/package.json index c32bebc..afefb7b 100644 --- a/package.json +++ b/package.json @@ -14,5 +14,5 @@ ] ], "deps": [], - "version": "0.9.0" + "version": "0.10.0" } \ No newline at end of file From d0638eb65ef7cdb45b47c8883e3668eb5d1a4f38 Mon Sep 17 00:00:00 2001 From: Jonas Scharpf Date: Tue, 1 Oct 2024 00:11:35 +0200 Subject: [PATCH 7/7] bump twine version --- requirements-deploy.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements-deploy.txt b/requirements-deploy.txt index e1bfff5..38eeeaa 100644 --- a/requirements-deploy.txt +++ b/requirements-deploy.txt @@ -1,6 +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