From f0de8eabdea1c3bb4b7d46763440f8d1183bf4b1 Mon Sep 17 00:00:00 2001 From: shamykyzer Date: Thu, 2 Apr 2026 13:40:47 +0100 Subject: [PATCH 1/2] ci: add git-cliff changelog automation --- .Rbuildignore | 1 + CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++ cliff.toml | 46 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 103 insertions(+) create mode 100644 cliff.toml diff --git a/.Rbuildignore b/.Rbuildignore index d2714dc..a495857 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -24,5 +24,6 @@ ^\.vscode$ ^.*\.swp$ ^\.Rdata$ +^cliff\.toml$ ^doc$ ^Meta$ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1cc612f..2b6773b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -74,6 +74,62 @@ writeLines(pak::pkg_system_requirements("devtools", "ubuntu", "22.04")) To remove the local virtual Python environment, delete the `r-acro` folder. On GNU/Linux this is typically located in `~/.virtualenvs` +## Pull Request Titles + +Use [Conventional Commits](https://www.conventionalcommits.org) for PR titles (squash-merge messages). This allows automated changelog generation. Common prefixes: + +``` +feat — new feature +fix — bug fix +docs — documentation changes +style — formatting/styling (no code logic) +refactor — code changes without feature/bug impact +perf — performance improvements +test — adding/updating tests +build — changes to build system or dependencies +ci — changes to CI config/scripts +chore — miscellaneous maintenance tasks +revert — reverts an earlier commit +``` + +## Release Workflow + +`NEWS.md` is generated locally before each release using [git-cliff](https://github.com/orhun/git-cliff). It reads merged PR titles (via squash-merge commit messages) since the last release tag and formats them to match the existing changelog style. + +### Install git-cliff + +Download a prebuilt binary from the [releases page](https://github.com/orhun/git-cliff/releases) or install via a package manager: + +```shell +# homebrew (macOS / Linux) +brew install git-cliff + +# winget (Windows) +winget install git-cliff +``` + +### Generate the changelog entry + +Run the following on `main` immediately before tagging a new release, replacing `X.Y.Z` with the new version: + +```shell +git cliff --config cliff.toml --unreleased --tag "VX.Y.Z" --prepend NEWS.md +``` + +Review and edit `NEWS.md` as needed (e.g. to add extra context or merge duplicate entries), then commit: + +```shell +git add NEWS.md +git commit -m "docs: update changelog" +git tag VX.Y.Z +``` + +The configuration lives in `cliff.toml` at the repository root. It automatically: + +- Converts `(#NNN)` PR references into markdown links. +- Skips noise commits (pre-commit auto-fixes, changelog and release-prep commits). +- Filters out commits that do not follow Conventional Commits (see [Pull Request Titles](#pull-request-titles)). + ## CRAN Submission A useful command to run before submitting: diff --git a/cliff.toml b/cliff.toml new file mode 100644 index 0000000..5306792 --- /dev/null +++ b/cliff.toml @@ -0,0 +1,46 @@ +[changelog] +header = "" +body = """ +{% if version %}\ +# acro {{ version | trim_start_matches(pat="V") }} ({{ timestamp | date(format="%b %d, %Y") }}) +{% else %}\ +# Unreleased +{% endif %}\ +{% for group, commits in commits | group_by(attribute="group") %} +### {{ group }} +{% for commit in commits -%} +* {% if commit.scope %}**{{ commit.scope }}:** {% endif %}{{ commit.message | trim }} +{% endfor %} +{%- endfor %}\ +""" +trim = true +footer = "" + +[git] +conventional_commits = true +filter_unconventional = true +# Only matches uppercase V tags (V0.1.7+); older lowercase tags +# (v0.1.1–v0.1.6) are excluded — their NEWS.md entries were hand-written. +tag_pattern = "V[0-9]+\\.[0-9]+\\.[0-9]+" + +commit_preprocessors = [ + { pattern = ' \(#(\d+)\)', replace = ' ([#$1](https://github.com/AI-SDC/ACRO-R/pull/$1))' }, +] + +commit_parsers = [ + { message = "^\\[pre-commit", skip = true }, + { message = "^docs: update changelog", skip = true }, + { message = "^docs: update citation", skip = true }, + { message = "^chore: prepare", skip = true }, + { message = "^feat", group = "feat" }, + { message = "^fix", group = "fix" }, + { message = "^docs", group = "docs" }, + { message = "^perf", group = "perf" }, + { message = "^refactor", group = "refactor" }, + { message = "^build", group = "build" }, + { message = "^test", group = "test" }, + { message = "^ci", group = "ci" }, + { message = "^style", group = "style" }, + { message = "^chore", group = "chore" }, + { message = "^revert", group = "revert" }, +] From 15627920475162b711e0f3b0c8b9ae0e2e05b16e Mon Sep 17 00:00:00 2001 From: shamykyzer Date: Wed, 29 Apr 2026 21:45:40 +0100 Subject: [PATCH 2/2] ci: catch non-conventional commits in changelog Apply Richard's review on PR #49. cliff.toml: - Set filter_unconventional to false and add a final ".*" parser that groups leftover commits under "Other". - Rename group labels to readable names (Features, Bug Fixes, etc.). - Add preprocessors that strip Signed-off-by trailers and multi-line commit bodies, so each entry is one tidy subject line. - Set trim to false so a blank line separates each release. CONTRIBUTING.md: - Update the cliff.toml summary to describe the new "Other" behavior. Repo-specific bits kept: uppercase V tag pattern, ACRO-R PR URL. --- CONTRIBUTING.md | 2 +- cliff.toml | 31 +++++++++++++++++-------------- 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b6773b..40bcb02 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,7 +128,7 @@ The configuration lives in `cliff.toml` at the repository root. It automatically - Converts `(#NNN)` PR references into markdown links. - Skips noise commits (pre-commit auto-fixes, changelog and release-prep commits). -- Filters out commits that do not follow Conventional Commits (see [Pull Request Titles](#pull-request-titles)). +- Groups commits that do not follow Conventional Commits under an "Other" heading so nothing is dropped (see [Pull Request Titles](#pull-request-titles)). ## CRAN Submission diff --git a/cliff.toml b/cliff.toml index 5306792..5025832 100644 --- a/cliff.toml +++ b/cliff.toml @@ -11,20 +11,22 @@ body = """ {% for commit in commits -%} * {% if commit.scope %}**{{ commit.scope }}:** {% endif %}{{ commit.message | trim }} {% endfor %} -{%- endfor %}\ +{%- endfor %} """ -trim = true +trim = false footer = "" [git] conventional_commits = true -filter_unconventional = true +filter_unconventional = false # Only matches uppercase V tags (V0.1.7+); older lowercase tags # (v0.1.1–v0.1.6) are excluded — their NEWS.md entries were hand-written. tag_pattern = "V[0-9]+\\.[0-9]+\\.[0-9]+" commit_preprocessors = [ { pattern = ' \(#(\d+)\)', replace = ' ([#$1](https://github.com/AI-SDC/ACRO-R/pull/$1))' }, + { pattern = 'Signed-off-by:.*', replace = '' }, + { pattern = '\n[\s\S]*', replace = '' }, ] commit_parsers = [ @@ -32,15 +34,16 @@ commit_parsers = [ { message = "^docs: update changelog", skip = true }, { message = "^docs: update citation", skip = true }, { message = "^chore: prepare", skip = true }, - { message = "^feat", group = "feat" }, - { message = "^fix", group = "fix" }, - { message = "^docs", group = "docs" }, - { message = "^perf", group = "perf" }, - { message = "^refactor", group = "refactor" }, - { message = "^build", group = "build" }, - { message = "^test", group = "test" }, - { message = "^ci", group = "ci" }, - { message = "^style", group = "style" }, - { message = "^chore", group = "chore" }, - { message = "^revert", group = "revert" }, + { message = "^feat", group = "Features" }, + { message = "^fix", group = "Bug Fixes" }, + { message = "^docs", group = "Documentation" }, + { message = "^perf", group = "Performance" }, + { message = "^refactor", group = "Refactoring" }, + { message = "^build", group = "Build" }, + { message = "^test", group = "Testing" }, + { message = "^ci", group = "CI" }, + { message = "^style", group = "Style" }, + { message = "^chore", group = "Chore" }, + { message = "^revert", group = "Reverts" }, + { message = ".*", group = "Other" }, ]