Improve changelog management

.github/workflows/changelog.yml

@@ -1,4 +1,4 @@
-name: Check changelog
+name: Changelog
 
 on:
   pull_request:
@@ -7,23 +7,58 @@ on:
     outputs:
       release_type:
         description: The release type extracted from changelog
-        value: ${{ jobs.check_changelog.outputs.release_type }}
+        value: ${{ jobs.validate_changelog.outputs.release_type }}
+      no_functional_changes:
+        description: A boolean indicating whether there are no functional changes in the changeset
+        value: ${{ jobs.check_functional_changes.outputs.no_functional_changes }}
+
 
 jobs:
-  check_changelog:
+  check_functional_changes:
+    runs-on: [ ubuntu-latest ]
+    outputs:
+      no_functional_changes: ${{ steps.set_no_functional_changes.outputs.no_functional_changes }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Make release type available to subsequent jobs # For backwards compatibility, as this workflow is used in other Open Terms Archive repositories
+        run: |
+          if grep -q "## Unreleased \[no-release\]" CHANGELOG.md; then
+            echo "NO_FUNCTIONAL_CHANGES=true" >> $GITHUB_ENV
+          fi
+
+      - name: Print result
+        id: set_no_functional_changes
+        run: |
+          echo "no_functional_changes='${{ env.NO_FUNCTIONAL_CHANGES }}'"
+          echo "no_functional_changes=${{ env.NO_FUNCTIONAL_CHANGES }}" >> $GITHUB_OUTPUT
+
+
+  validate_changelog:
+    if: ${{ needs.check_functional_changes.outputs.no_functional_changes != 'true' }}
+    needs: [ check_functional_changes ]
     runs-on: [ ubuntu-latest ]
     outputs:
       release_type: ${{ steps.set_release_type_output.outputs.release_type }}
     steps:
       - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Print previous job result
+        run: |
+          echo "Result previous job: '${{ needs.check_functional_changes.outputs.no_release }}'"
+
+      - name: Validate changelog
+        run: npm run changelog --silent -- --validate
+
       - name: Get release type in changelog
-        run: echo "RELEASE_TYPE=$(cat CHANGELOG.md | grep -E '^## Unreleased \[(patch|minor|major)\]$' | grep -E -w -o "patch|minor|major" | tr -d '\n')" >> $GITHUB_ENV
-      - name: Make release type available to subsequent jobs
+        run: echo "RELEASE_TYPE=$(npm run changelog --silent -- --get-release-type)" >> $GITHUB_ENV
+
+      - name: Make release type available to subsequent jobs # For backwards compatibility, as this workflow is used in other Open Terms Archive repositories
         if: env.RELEASE_TYPE
         id: set_release_type_output
         run: |
           echo "Found release type '${{ env.RELEASE_TYPE }}'"
           echo "release_type=${{ env.RELEASE_TYPE }}" >> $GITHUB_OUTPUT
-      - name: Fail and display error if no proper release type is found in changelog
-        if: env.RELEASE_TYPE == ''
-        run: echo "No valid release type found in changelog. The title of the 'Unreleased' section must contain one of the following tags '[patch]', '[minor]', '[major]'. For example, '## Unreleased [minor]'."; exit 1

.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
   test:
     uses: "OpenTermsArchive/engine/.github/workflows/test.yml@main"
   release:
-    if: github.event.pull_request.merged == true
+    if: github.event.pull_request.merged == true && needs.changelog.outputs.no_functional_changes != 'true'
     needs: [ changelog, test ]
     runs-on: ubuntu-latest
     steps:
@@ -22,22 +22,21 @@ jobs:
         with:
           token: ${{ secrets.RELEASE_BOT_GITHUB_TOKEN }}
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Configure Git author
         run: |
           git config --global user.name "Open Terms Archive Release Bot"
           git config --global user.email "release-bot@opentermsarchive.org"
 
       - name: Bump package version
         run: |
-          echo "Release type obtained from the previous job: '${{ needs.changelog.outputs.release_type }}'"
-          echo "NEW_VERSION=$(npm --no-git-tag-version version ${{ needs.changelog.outputs.release_type }})" >> $GITHUB_ENV
+          echo "Release type found: '$(npm run changelog --silent -- --get-release-type)'"
+          echo "NEW_VERSION=$(npm --no-git-tag-version version $(npm run changelog --silent -- --get-release-type))" >> $GITHUB_ENV
 
       - name: Update changelog unreleased section with new version
-        uses: superfaceai/release-changelog-action@v2
-        with:
-          version: ${{ env.NEW_VERSION }}
-          operation: release
-          format: markdownlint
+        run: npm run changelog --silent -- --release ${{ github.event.number }} # github.event.number refers to the pull request number
 
       - name: Commit CHANGELOG.md and package.json changes and create tag
         run: |
@@ -58,17 +57,16 @@ jobs:
         run: git push origin && git push --tags
 
       - name: Read version changelog
-        uses: superfaceai/release-changelog-action@v2
-        id: get-changelog
-        with:
-          version: ${{ env.NEW_VERSION }}
-          operation: read
+        run: |
+          echo "VERSION_CHANGELOG<<EOF" >> $GITHUB_ENV
+          echo "$(npm run changelog --silent -- --get-version-content ${{ env.NEW_VERSION }})" >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
 
       - name: Create GitHub release
         uses: softprops/action-gh-release@v1
         with:
           tag_name: ${{ env.NEW_VERSION }}
-          body: ${{ steps.get-changelog.outputs.changelog }}
+          body: ${{ env.VERSION_CHANGELOG }}
           token: ${{ secrets.RELEASE_BOT_GITHUB_TOKEN }}
 
       - name: Publish to NPM public repository
@@ -83,3 +81,26 @@ jobs:
           event-type: engine-release
           repository: OpenTermsArchive/docs
           client-payload: '{"version": "${{ env.NEW_VERSION }}"}'
+
+  clean_changelog:
+    if: github.event.pull_request.merged == true && needs.changelog.outputs.no_functional_changes == 'true'
+    needs: [ changelog ]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.RELEASE_BOT_GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Configure Git author
+        run: |
+          git config --global user.name "Open Terms Archive Release Bot"
+          git config --global user.email "release-bot@opentermsarchive.org"
+
+      - name: Revert CHANGELOG.md
+        run: |
+          npm run changelog --silent -- --clean-unreleased
+          git commit -m "Clean changelog" CHANGELOG.md
+          git push origin

CHANGELOG.md

@@ -2,7 +2,9 @@
 
 All changes that impact users of this module are documented in this file, in the [Common Changelog](https://common-changelog.org) format with some additional specifications defined in the CONTRIBUTING file. This codebase adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## Unreleased [no-release]
+
+_Modifications made in this changeset do not alter its behavior or functionality from the perspective of the end user or other interacting systems. It does not add new features, does not enhance existing features, or alters the behavior of the software in a way that affects its use._
 
 ## 0.37.1 - 2024-02-20
 

CONTRIBUTING.md

@@ -61,11 +61,19 @@ All changes to the codebase that impact users must be documented in the [`CHANGE
 
 The format to use is [Common Changelog](https://common-changelog.org), with the following additional specifications:
 
-1. The `unreleased` section of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) is preserved with the addition of a tag to specify which type of release should be published and to foster discussions about it inside pull requests. This tag should be one of the names mandated by SemVer, within brackets: `[patch]`, `[minor]` or `[major]`. For example: `## Unreleased [minor]`.
+1. The `unreleased` section of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) must be added in the changelog with the addition of a tag to specify which type of release should be published and to foster discussions about it inside pull requests. This tag should be one of the names mandated by SemVer, within brackets: `[patch]`, `[minor]` or `[major]`. For example: `## Unreleased [minor]`.<br>
+For non-functional changes (docs, refactors, internal tooling, …) that should not trigger a release, the following content should be added to the changelog:
+
+  ```
+  ## Unreleased [no-release]
+
+  _Modifications made in this changeset do not alter its behavior or functionality from the perspective of the end user or other interacting systems. It does not add new features, does not enhance existing features, or alters the behavior of the software in a way that affects its use._
+  ```
+
 2. Each listed change must provide an actionable way to adapt the user’s codebase, either directly in the changelog or through instructions or links.
 3. Changes are a single sentence with no punctuation (like all examples given in Common Changelog).
-4. Since each release is produced automatically from a single pull request, the [notice](https://common-changelog.org/#23-notice) is always used to link to the source pull request rather than [references](https://common-changelog.org/#242-references), which would always reference the same pull request. References can instead link to relevant specific parts of an RFC, decision record or diff.
-5. The [notice](https://common-changelog.org/#23-notice) is also used to present sponsor information. Since the development of this project is funded by different actors, and following discussions with sponsors, financial contributions are acknowledged in the changelog itself. The format of the notice thus diverges from the Common Changelog specification in that it is not “a single-sentence paragraph”. Sponsor information is in quote format, starts with “Development of this release was supported by <funding_from>”, and provides the name and link to the sponsor, as well as information on the specific funding instrument, as specified by the sponsor itself or as required by law. A short message from the sponsor might also be added, as long as it abides by the community’s [Code of Conduct](./CODE_OF_CONDUCT.md) and aligns with the project’s goals.
+4. Since each release is produced automatically from a single pull request, the [notice](https://common-changelog.org/#23-notice) is always used to link to the source pull request rather than [references](https://common-changelog.org/#242-references), which would always reference the same pull request. References can instead link to relevant specific parts of an RFC, decision record or diff. This notice is auto generated by the release process.
+5. The [notice](https://common-changelog.org/#23-notice) is also used to present sponsor information and it is required. Since the development of this project is funded by different actors, and following discussions with sponsors, financial contributions are acknowledged in the changelog itself. The format of the notice thus diverges from the Common Changelog specification in that it is not “a single-sentence paragraph”. Sponsor information is in quote format, starts with “Development of this release was supported by <funding_from>”, and provides the name and link to the sponsor, as well as information on the specific funding instrument, as specified by the sponsor itself or as required by law. A short message from the sponsor might also be added, as long as it abides by the community’s [Code of Conduct](./CODE_OF_CONDUCT.md) and aligns with the project’s goals.
 
 ## Development
 

package.json

@@ -30,6 +30,7 @@
     ".eslintrc.yaml"
   ],
   "scripts": {
+    "changelog": "node scripts/changelog/index.js",
     "dataset:generate": "node bin/ota.js dataset",
     "dataset:release": "node bin/ota.js dataset --publish --remove-local-copy",
     "dataset:scheduler": "npm run dataset:release -- --schedule",
@@ -81,6 +82,7 @@
     "joplin-turndown-plugin-gfm": "^1.0.12",
     "jsdom": "^18.1.0",
     "json-source-map": "^0.6.1",
+    "keep-a-changelog": "^2.5.3",
     "lodash": "^4.17.21",
     "mime": "^2.5.2",
     "mocha": "^9.1.3",
@@ -92,6 +94,7 @@
     "puppeteer": "14.3.0",
     "puppeteer-extra": "^3.2.3",
     "puppeteer-extra-plugin-stealth": "^2.9.0",
+    "semver": "^7.6.0",
     "sib-api-v3-sdk": "^8.2.1",
     "simple-git": "^3.8.0",
     "swagger-jsdoc": "^6.2.8",