build: make rake changelog non-destructive; adopt conventional commits

CHANGELOG.md

@@ -3,6 +3,17 @@ All notable changes to this project will be documented in this file.
 This file should follow the standards specified on [http://keepachangelog.com/]
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [12.0.0] (2026-08-16)
+
+### Changed
+- Use the driver-native Neo4j::Driver::Types::Duration instead of ActiveSupport::Duration
+
+### Added
+- Type converted for ActiveSupport::Duration to Neo4j::Driver::Types::Duration for backward compatibility. The converter is lossy if fractional units are used in ActiveSupport::Duration.
+
+### Fixed
+- Adapt to neo4j-ruby-driver 6.2.1
+
 ## [12.0.0.beta.7] (2026-03-19)
 
 ### Fixed

CLAUDE.md

@@ -0,0 +1,41 @@
+# Working conventions for activegraph
+
+## Commit messages — Conventional Commits (required going forward)
+
+All new commits **and PR titles** must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+type(optional-scope): short imperative subject
+```
+
+PRs are **squash-merged**, so the PR title becomes the single commit on the
+default branch — write the PR title as a conventional commit.
+
+Types that appear in the generated changelog (see `cliff.toml`):
+
+| type   | Changelog section |
+|--------|-------------------|
+| `feat` | Added             |
+| `fix`  | Fixed             |
+| `perf` | Performance       |
+
+Other valid types are fine but are **excluded** from the changelog:
+`chore`, `ci`, `docs`, `refactor`, `test`, `style`, `build`, `revert`.
+
+Examples:
+- `feat(node): support composite id_property constraints`
+- `fix(query): escape backticks in relationship type names`
+- `perf: batch index lookups in schema inspection`
+- `ci: skip the matrix on docs-only changes`
+
+Reference a PR/issue in the subject as `(#1234)` — `cliff.toml` turns it into a link.
+
+## CHANGELOG.md
+
+- The `[Unreleased]` section is generated from conventional commits:
+  `rake changelog` (refresh) / `rake "changelog[v12.0.0.beta.8]"` (finalize a
+  version at release).
+- The task is **non-destructive**: it only rewrites the top `[Unreleased]`/version
+  section and inserts it under the preamble. Everything below is **hand-written
+  history from before conventional commits were adopted — never regenerate or
+  overwrite it** (git-cliff can't reproduce those non-conventional commits).

Rakefile

@@ -55,19 +55,41 @@ task 'coverage' do
   task.invoke
 end
 
-# Regenerate CHANGELOG.md from the commit history with git-cliff
-# (https://git-cliff.org; `brew install git-cliff`). Run after merging PRs to
-# refresh [Unreleased]; pass the release tag to finalize a version section:
-#   rake "changelog[v12.0.0.beta.7]"
-desc 'Regenerate CHANGELOG.md from commits (git-cliff)'
+# Refresh CHANGELOG.md's [Unreleased] section from conventional commits with
+# git-cliff (https://git-cliff.org; `brew install git-cliff`). Non-destructive:
+# generates only the new (unreleased) entries and inserts them under the
+# preamble, leaving the hand-written history below untouched — activegraph's
+# pre-conventional-commit history can't be regenerated. Pass the release tag to
+# finalize the section as a version at release time:
+#   rake "changelog[v12.0.0.beta.8]"
+desc 'Refresh CHANGELOG.md [Unreleased] from conventional commits (git-cliff)'
 task :changelog, [:tag] do |_task, args|
-  cmd = %w[git cliff]
+  cmd = %w[git cliff --unreleased --strip all]
   if (tag = args[:tag])
-    tag.match?(/\Av\d[\w.-]*\z/) or raise "Invalid tag #{tag.inspect} (expected e.g. v12.0.0.beta.7)" # rubocop:disable Style/AndOr
+    # array form (no shell) means the tag can't inject commands
+    tag.match?(/\Av\d[\w.-]*\z/) or raise "Invalid tag #{tag.inspect} (expected e.g. v12.0.0.beta.8)" # rubocop:disable Style/AndOr
     cmd += ['--tag', tag]
   end
-  # Pass args to sh as an array — no shell, so the tag can't inject commands.
-  sh(*cmd, '-o', 'CHANGELOG.md')
+  require 'open3'
+  section, stderr, status = Open3.capture3(*cmd)
+  warn stderr unless stderr.empty?  # surface git-cliff's own warnings (e.g. skipped commits)
+  abort "git-cliff failed (exit #{status.exitstatus})" unless status.success?
+  section = section.strip
+  # git-cliff still emits a bare `## [<id>]` heading with no entries when nothing
+  # matched — only touch the file when there's at least one entry.
+  abort 'git-cliff produced no entries (no conventional commits since the last release).' unless section.match?(/^- /)
+  # generated heading is `## [Unreleased]`, or `## [<version>]` when a tag is given
+  id = section[/\A## \[([^\]]+)\]/, 1]
+  changelog = File.read('CHANGELOG.md')
+  # drop a stale [Unreleased] and any existing section for the target id (so a
+  # re-run at release is idempotent); the lookahead stops at the next heading or
+  # end of file, so a trailing section is handled too
+  ['Unreleased', id].uniq.each do |heading|
+    changelog = changelog.sub(/^## \[#{Regexp.escape(heading)}\].*?(?=^## \[|\z)/m, '')
+  end
+  changelog = changelog.sub(/^(?=## \[)/, "#{section}\n\n")  # insert under the preamble
+  File.write('CHANGELOG.md', changelog)
+  puts "Updated CHANGELOG.md:\n#{section}"
 end
 
 task default: ['spec']

lib/active_graph/version.rb

@@ -1,3 +1,3 @@
 module ActiveGraph
-  VERSION = '12.0.0.beta.7'
+  VERSION = '12.0.0'
 end