Merge pull request #173 from oasisprotocol/mz/ci-lint

Init Change Log fragments

Author: buberdds

.changelog/.markdownlint.yml

@@ -0,0 +1,24 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json
+
+# markdownlint configuration for Change Log fragments.
+
+# For more information, see:
+# https://github.com/DavidAnson/markdownlint#optionsconfig.
+
+# Extend project's main configuration.
+extends: ../.markdownlint.yml
+
+line-length:
+  # Line length checking is not strict by default.
+  strict: true
+  # Change Log fragments will be listed as bullets indented by 2 spaces so they
+  # should be 2 characters shorter than ordinary lines.
+  line_length: 78
+
+# Change Log fragments should not have a heading as the first line.
+first-line-heading: false
+
+ul-style:
+  # Enforce a uniform symbol for unordered lists across all Change Log
+  # fragments.
+  style: dash

.changelog/173.process.md

@@ -0,0 +1,8 @@
+Add Change Log and the Change Log fragments process for assembling it
+
+This follows the same Change Log fragments process as is used by [Oasis Core].
+
+For more details, see [Change Log fragments].
+
+[Oasis Core]: https://github.com/oasisprotocol/oasis-core
+[Change Log fragments]: .changelog/README.md

.changelog/README.md

@@ -0,0 +1,15 @@
+# Change Log Fragments
+
+This directory collects Change Log fragments:
+short files that each contain a snippet of Markdown formatted text that will
+be assembled using [towncrier] to form the [Change Log] section for the next
+release.
+
+This repository follows the same Change Log fragments style as the
+[Oasis Core] repository.
+Please, see [its Change Log fragments documentation] for more details.
+
+[Change Log]: ../CHANGELOG.md
+[towncrier]: https://github.com/oasisprotocol/towncrier
+[Oasis Core]: https://github.com/oasisprotocol/oasis-core
+[its Change Log fragments documentation]: https://github.com/oasisprotocol/oasis-core/blob/master/.changelog/README.md

.changelog/template.md.j2

@@ -0,0 +1,39 @@
+{# This a Jinja2 template for preparing a new section of the Change Log with the towncrier utility.#}
+## {{ versiondata.version }} ({{ versiondata.date }})
+{% for section, _ in sections.items() %}
+
+{% if sections[section] %}
+{% for category, val in definitions.items() if category in sections[section] %}
+{% if definitions[category]['showcontent'] %}
+{{ "### " + definitions[category]['name'] }}
+
+{% for text, values in sections[section][category].items() %}
+{% set lines = text.splitlines() %}
+{% set referenced_issues = "(" + values | join(',\n   ') + ")" %}
+{% if lines | length > 2 and lines[1] == "" %}
+- {{ lines[0] }}
+  {{ referenced_issues }}
+
+{{ lines[2:] | join('\n') }}
+{% else %}
+- {{ text }}
+  {{ referenced_issues }}
+{% endif %}
+{% if not loop.last %}
+
+{% endif %}
+{% endfor %}
+{% endif %}
+{% if sections[section][category]|length == 0 %}
+No significant changes.
+
+{% else %}
+{% endif %}
+
+{% endfor %}
+{% else %}
+No significant changes.
+
+
+{% endif %}
+{% endfor %}

.github/workflows/ci-lint.yml

@@ -58,11 +58,33 @@ jobs:
       - name: Install gitlint
         run: |
           python -m pip install gitlint
+        # Needed for Towncrier fork to work with 3.12 and above
+      - name: Install setuptools
+        run: |
+          python -m pip install setuptools
+      - name: Install towncrier
+        run: |
+          python -m pip install https://github.com/oasisprotocol/towncrier/archive/oasis-master.tar.gz
+      - name: Check for presence of a Change Log fragment (only pull requests)
+        # NOTE: The pull request' base branch needs to be fetched so towncrier
+        # is able to compare the current branch with the base branch.
+        # Source: https://github.com/actions/checkout/#fetch-all-branches.
+        run: |
+          git fetch --no-tags origin "+refs/heads/${BASE_BRANCH}:refs/remotes/origin/${BASE_BRANCH}"
+          towncrier check --compare-with "origin/${BASE_BRANCH}"
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+        if: github.event_name == 'pull_request'
       - name: Lint documentation
         run: |
           pnpm lint-docs
         # Always run this step so that all linting errors can be seen at once.
         if: always()
+      - name: Lint Change Log fragments
+        run: |
+          pnpm lint-changelog
+        # Always run this step so that all linting errors can be seen at once.
+        if: always()
       - name: Lint git commits
         run: |
           pnpm lint-git

.github/workflows/deploy-gh-pages.yaml

@@ -10,7 +10,6 @@ on:
       # For more details on GitHub Actions' pattern match syntax, see:
       # https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#patterns-to-match-branches-and-tags.
       - 'v[0-9]+.[0-9]+*'
-  workflow_dispatch: # Manual
 
 jobs:
   build:

.markdownlint.yml

@@ -11,9 +11,11 @@ default: true
 line-length:
   # Line length checking is not strict by default.
   strict: true
-  line_length: 120
+  line_length: 80
   # Allow longer lines for code blocks.
   code_block_line_length: 100
+  # Ignore on tables
+  tables: false
 
 # Do not always require language specifiers with fenced code blocks since they
 # are not part of the Markdown spec.

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Change Log
+
+All notables changes to this project are documented in this file.
+
+The format is inspired by [Keep a Changelog].
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+
+<!-- markdownlint-disable no-duplicate-heading -->
+
+<!-- NOTE: towncrier will not alter content above the TOWNCRIER line below. -->
+
+<!-- TOWNCRIER -->

internals/scripts/changelog.js

@@ -0,0 +1,39 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+/* eslint-disable no-undef */
+const execSync = require('child_process').execSync
+const semver = require('semver')
+const glob = require('glob')
+const packageJson = require('../../package.json')
+
+const folderPath = '.changelog/'
+const majorPattern = `${folderPath}*breaking*.md`
+const minorPattern = `${folderPath}*feature*.md`
+const patchPattern = `${folderPath}*{process,cfg,bugfix,doc,internal,trivial}*.md`
+
+console.log('Assembling Change Log and updating package version')
+
+let version = packageJson.version
+if (glob.sync(majorPattern).length > 0) {
+  console.log('\x1b[31m%s\x1b[0m', 'Warning: This release contains breaking changes.')
+  version = semver.inc(version, 'major')
+} else if (glob.sync(minorPattern).length > 0) {
+  version = semver.inc(version, 'minor')
+} else if (glob.sync(patchPattern).length > 0) {
+  version = semver.inc(version, 'patch')
+} else {
+  console.log('No Change Log fragments found. Aborting release...')
+  process.exit(1)
+}
+
+if (!semver.valid(version)) {
+  console.log(`Invalid version: ${version}`)
+  process.exit(1)
+}
+
+if (semver.lte(version, packageJson.version)) {
+  console.log(`Version ${version} is not greater than ${packageJson.version}`)
+  process.exit(1)
+}
+
+execSync(`pnpm version --no-git-tag-version ${version}`, { stdio: 'inherit' })
+execSync(`towncrier build --version ${version}`, { stdio: 'inherit' })

package.json

@@ -8,6 +8,8 @@
     "eslint": "eslint . --cache --ext .js,.ts,.tsx --max-warnings 0",
     "lint-git": "node ./internals/scripts/gitlint.mjs",
     "lint-docs": "markdownlint --ignore '**/node_modules/**' '**/*.md'",
+    "lint-changelog": "markdownlint --config .changelog/.markdownlint.yml .changelog/",
+    "changelog": "node ./internals/scripts/changelog.js",
     "release-tag": "node ./internals/scripts/release-tag.js",
     "prettier-check": "prettier --check . --ignore-path .eslintignore",
     "prettier": "prettier --write . --ignore-path .eslintignore",
@@ -31,9 +33,11 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-refresh": "^0.4.5",
+    "glob": "^11.0.1",
     "husky": "^9.0.11",
     "lint-staged": "^15.2.2",
     "markdownlint-cli": "^0.39.0",
-    "prettier": "^3.2.5"
+    "prettier": "^3.2.5",
+    "semver": "^7.7.1"
   }
 }