LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

# 自上次标签以来的所有提交（完整信息）
git log ${LAST_TAG}..HEAD --format="COMMIT_START%nHash: %H%nShort: %h%nAuthor: %aN <%aE>%nDate: %ai%nSubject: %s%nBody: %b%nCOMMIT_END"

# 单行摘要
git log ${LAST_TAG}..HEAD --oneline

# 包含文件变更
git log ${LAST_TAG}..HEAD --oneline --name-status

# 差异统计
git diff --stat ${LAST_TAG}..HEAD

# 贡献者
git log ${LAST_TAG}..HEAD --format='%aN' | sort | uniq -c | sort -rn

收集已合并的 PR（GitHub）

# 列出自上次标签日期以来已合并的 PR
LAST_TAG_DATE=$(git log -1 --format=%ci $(git describe --tags --abbrev=0 2>/dev/null) 2>/dev/null)

# 使用 gh CLI
gh pr list --state merged --search "merged:>=${LAST_TAG_DATE}" --json number,title,labels,author,body --limit 100

# 替代方案：从合并提交中提取 PR 编号
git log ${LAST_TAG}..HEAD --oneline --grep="Merge pull request" | grep -oE "#[0-9]+"
git log ${LAST_TAG}..HEAD --oneline --grep="(#[0-9]+)" | grep -oE "#[0-9]+"

收集已合并的 MR（GitLab）

# 使用 glab CLI
glab mr list --state merged --json number,title,labels,author

3. 分类变更

解析约定式提交

根据前缀对提交进行分类：

如果提交不符合约定式格式

当提交不遵循约定式格式时，分析差异以分类：

# 分析变更区域
git diff --stat ${LAST_TAG}..HEAD | tail -1  # 摘要

# 按目录/模块分组
git diff --name-only ${LAST_TAG}..HEAD | sed 's|/.*||' | sort | uniq -c | sort -rn

# 在提交信息中查找关键词
git log ${LAST_TAG}..HEAD --oneline | grep -iE "fix|bug|patch|resolve" # 错误修复
git log ${LAST_TAG}..HEAD --oneline | grep -iE "add|new|feature|implement|support" # 功能
git log ${LAST_TAG}..HEAD --oneline | grep -iE "remove|delete|deprecate|drop" # 移除
git log ${LAST_TAG}..HEAD --oneline | grep -iE "update|upgrade|bump|depend" # 依赖项
git log ${LAST_TAG}..HEAD --oneline | grep -iE "perf|speed|fast|optim|cache" # 性能
git log ${LAST_TAG}..HEAD --oneline | grep -iE "security|vuln|cve|auth" # 安全
git log ${LAST_TAG}..HEAD --oneline | grep -iE "refactor|clean|restructure" # 重构
git log ${LAST_TAG}..HEAD --oneline | grep -iE "doc|readme|comment" # 文档
git log ${LAST_TAG}..HEAD --oneline | grep -iE "test|spec|coverage" # 测试
git log ${LAST_TAG}..HEAD --oneline | grep -iE "ci|pipeline|workflow|deploy" # CI/CD

检测破坏性变更

# 在提交正文中检查 BREAKING CHANGE
git log ${LAST_TAG}..HEAD --format="%B" | grep -i "BREAKING CHANGE"

# 检查移除的导出/端点
git diff ${LAST_TAG}..HEAD -- "*.ts" "*.js" | grep -E "^-export|^-module\.exports"
git diff ${LAST_TAG}..HEAD -- "*.py" | grep -E "^-def |^-class "

# 检查移除的 API 路由
git diff ${LAST_TAG}..HEAD -- "*route*" "*controller*" "*endpoint*" | grep "^-"

# 检查删除/重命名的数据库迁移
find . -name "*.sql" -newer $(git rev-parse ${LAST_TAG}) | xargs grep -liE "DROP|RENAME|ALTER.*DROP" 2>/dev/null

# 检查更改的配置/环境要求
git diff ${LAST_TAG}..HEAD -- ".env.example" "*.config.*" "docker-compose.*"

4. 更新日志格式

格式 A：保持更新日志（推荐用于库/开源软件）

遵循 keepachangelog.com 格式：

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [2.4.0] - 2026-02-17

### Added
- OAuth2 login support with Google and GitHub providers (#234)
- Real-time order status notifications via WebSocket (#241)
- Bulk export of analytics data in CSV and JSON formats (#238)
- Rate limiting on all public API endpoints (#245)

### Changed
- Upgraded Next.js from 14.2 to 15.1 (#250)
- Migrated email service from Mailgun to SendGrid (#247)
- Improved search indexing performance by 3x with batch processing (#243)

### Fixed
- Fixed duplicate charge on payment retry when Stripe webhook is delayed (#236)
- Fixed pagination returning wrong total count on filtered queries (#239)
- Fixed timezone handling in scheduled report generation (#242)
- Fixed memory leak in WebSocket connection handler (#248)

### Security
- Patched XSS vulnerability in user profile bio field (#237)
- Updated jsonwebtoken to 9.0.2 to fix CVE-2024-XXXXX (#246)

### Deprecated
- The `/api/v1/reports` endpoint is deprecated in favor of `/api/v2/analytics`. Will be removed in v3.0.0.

### Removed
- Removed legacy CSV import endpoint `/api/v1/import/csv` (use `/api/v2/import` instead)

## [2.3.1] - 2026-01-28

### Fixed
- ...

[Unreleased]: https://github.com/org/repo/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/org/repo/compare/v2.3.1...v2.4.0
[2.3.1]: https://github.com/org/repo/compare/v2.3.0...v2.3.1

格式 B：面向用户的发布说明（适用于产品/应用）

为最终用户编写，而非开发者：

# v2.4.0 版本的新功能 🚀

发布日期：2026年2月17日

## 亮点

### 使用 Google 和 GitHub 登录
您现在可以使用您的 Google 或 GitHub 账户登录 — 无需再记住密码。前往 设置 → 账户 → 已连接账户 来关联您的账户。

### 实时订单追踪
实时查看您的订单状态更新。无需再刷新页面 — 状态变更的瞬间您就能看到。

### 批量数据导出
以 CSV 或 JSON 格式导出您的分析数据。非常适合自定义报告或导入到您自己的工具中。在 分析 → 导出 下找到此功能。

## 改进

- **更快的搜索**：搜索结果现在加载速度快了3倍，尤其是在大型目录上
- **更好的邮件**：我们已迁移到更可靠的邮件提供商 — 订单确认邮件的延迟更少
- **API 速率限制**：添加了速率限制以防止滥用并确保性能稳定

## 错误修复

- 修复了在结账过程中连接断开时可能重复扣款的问题
- 修复了筛选产品列表时页面计数不正确的问题
- 修复了某些地区计划报告显示错误时区的问题
- 修复了应用在长时间保持连接后可能变慢的罕见问题

## 安全

- 修复了用户个人资料中可能允许脚本注入的文本渲染问题
- 更新了安全库以修补已知漏洞

## 破坏性变更

⚠️ **API v1 报告端点已弃用**
`/api/v1/reports` 端点现已弃用。请在 2026年7月 v1 版本移除前迁移到 `/api/v2/analytics`。
详情请参阅我们的[迁移指南](link)。

## 升级说明

大多数用户无需任何操作。如果您使用我们的 API：
- 将使用 `/api/v1/import/csv` 的任何代码更新为 `/api/v2/import`
- 在您的 API 客户端中添加速率限制处理（429 响应）

---

**完整更新日志**：[v2.3.1...v2.4.0](https://github.com/org/repo/compare/v2.3.1...v2.4.0)

格式 C：开发者发布说明（适用于内部团队）

技术性强且详细，面向工程团队：

# 发布 v2.4.0

**日期**：2026-02-17
**标签**：v2.4.0
**提交**：来自 8 位贡献者的 47 次提交
**已合并的 PR**：16

## 摘要

此版本添加了 OAuth2 身份验证、实时 WebSocket 通知和批量数据导出。主要基础设施变更：电子邮件从 Mailgun 迁移到 SendGrid。搜索索引性能改进（快 3 倍）。

## 破坏性变更

### API
- `DELETE /api/v1/import/csv` — 已移除。使用带有 `format: "csv"` 请求头的 `POST /api/v2/import`
- `GET /api/v1/reports` — 已弃用（仍可用）。返回 `Sunset: 2026-07-01` 请求头

### 数据库
- 迁移 `20260215_add_oauth_providers` 添加了 `oauth_providers` 表和 `users.oauth_id` 列
- 迁移 `20260216_add_websocket_sessions` 添加了 `ws_sessions` 表

### 环境变量
- **新增必需项**：`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
- **新增必需项**：`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
- **新增必需项**：`SENDGRID_API_KEY`（替换 `MAILGUN_API_KEY`）
- **已移除**：`MAILGUN_API_KEY`, `MAILGUN_DOMAIN`

## 按领域划分的变更

### 身份验证 (#234, #237)
- 添加了带有 PKCE 的 Google 和 GitHub OAuth2 流程
- 新表：`oauth_providers`, `oauth_tokens`
- 修改：`users` 表（添加了 `oauth_id`, `oauth_provider` 列）
- 修补了个人资料简介中的 XSS（使用 DOMPurify 进行清理）
- 文件：`src/services/auth/`, `src/api/routes/auth.ts`, `src/db/migrations/`

### 实时通知 (#241, #248)
- 在 `/ws` 路径上使用 `ws` 库的 WebSocket 服务器
- 用于多实例广播的 Redis 发布/订阅
- 修复了连接泄漏（缺少 `close` 事件处理程序）
- 文件：`src/services/websocket/`, `src/lib/redis-pubsub.ts`

### 数据导出 (#238)
- 新端点：`POST /api/v2/analytics/export`
- 支持 CSV 和 JSON 输出
- 流式传输大型数据集的结果（无内存问题）
- 文件：`src/api/routes/analytics.ts`, `src/services/export/`

### 搜索性能 (#243)
- 批量索引：每批 100 个项目，而非逐个处理
- 添加了 Redis 缓存层（5 分钟 TTL）
- 平均索引时间从 3.2 秒减少到 0.9 秒
- 文件：`src/services/search/`, `src/lib/cache.ts`

### 电子邮件迁移 (#247)
- 将 Mailgun SDK 替换为 SendGrid v3
- 更新了所有电子邮件模板（外观相同，模板引擎不同）
- 添加了用于退回跟踪的电子邮件送达 Webhook
- 文件：`src/lib/email.ts`, `src/templates/email/`

### 基础设施 (#245, #246, #250)
- 添加了 express-rate-limit：公共端点上每个 IP 每分钟 100 次请求
- 升级 Next.js 14.2 → 15.1（React 19，Server Actions 稳定版）
- 更新 jsonwebtoken 8.5.1 → 9.0.2（CVE 修复）

## 部署清单

- [ ] 运行数据库迁移（`npm run db:migrate`）
- [ ] 添加新的环境变量（参见破坏性变更）
- [ ] 移除旧的 Mailgun 环境变量
- [ ] 验证 SendGrid API 密钥是否具有正确的权限
- [ ] 验证 OAuth 回调 URL 是否已在 Google/GitHub 注册
- [ ] 部署后监控 WebSocket 连接（新功能）
- [ ] 监控电子邮件送达率（新提供商）
- [ ] 验证速率限制是否未阻止合法流量

## 回滚计划

如果出现问题：
1. 回退到 v2.3.1 标签：`git checkout v2.3.1`
2. 运行向下迁移：`npm run db:migrate:down -- --to 20260214`
3. 恢复旧的环境变量（MAILGUN_*）
4. 重新部署

## 贡献者

- @alice — OAuth2 实现，安全修复
- @bob — WebSocket 通知，连接泄漏修复
- @carol — 数据导出，搜索性能
- @dave — 电子邮件迁移，Next.js 升级
- @eve — 速率限制，依赖项更新

## 统计

| 指标 | 值 |
|--------|-------|
| 提交 | 47 |
| 已合并的 PR | 16 |
| 更改的文件 | 83 |
| 新增行数 | +3,241 |
| 删除行数 | -1,087 |
| 新测试 | 34 |
| 贡献者 | 8 |

格式 D：紧凑型更新日志（适用于快速发布）

适用于频繁发布团队的简短格式：

## v2.4.0 (2026-02-17)

**功能**：OAuth2 登录（Google/GitHub）(#234)，实时订单通知 (#241)，批量数据导出 (#238)
**修复**：重复支付扣款 (#236)，分页计数 (#239)，报告时区 (#242)，WebSocket 内存泄漏 (#248)
**安全**：个人资料简介中的 XSS (#237)，jsonwebtoken CVE (#246)
**性能**：搜索索引快 3 倍 (#243)
**基础设施**：Next.js 15.1 (#250)，Mailgun → SendGrid (#247)，API 速率限制 (#245)
**破坏性变更**：移除了 `/api/v1/import/csv`，弃用了 `/api/v1/reports`
**新环境变量**：`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `SENDGRID_API_KEY`

5. 版本号更新建议

语义化版本控制规则

根据检测到的变更，建议适当的版本号更新：

# 根据提交建议版本
HAS_BREAKING=$(git log ${LAST_TAG}..HEAD --format="%B" | grep -ci "BREAKING CHANGE\|breaking:")
HAS_FEAT=$(git log ${LAST_TAG}..HEAD --format="%s" | grep -ci "^feat")
HAS_FIX=$(git log ${LAST_TAG}..HEAD --format="%s" | grep -ci "^fix")

CURRENT=$(git describe --tags --abbrev=0 | sed 's/^v//')
MAJOR=$(echo $CURRENT | cut -d. -f1)
MINOR=$(echo $CURRENT | cut -d. -f2)
PATCH=$(echo $CURRENT | cut -d. -f3)

if [ "$HAS_BREAKING" -gt "0" ]; then
  echo "Suggested: v$((MAJOR+1)).0.0 (MAJOR — breaking changes detected)"
elif [ "$HAS_FEAT" -gt "0" ]; then
  echo "Suggested: v${MAJOR}.$((MINOR+1)).0 (MINOR — new features)"
else
  echo "Suggested: v${MAJOR}.${MINOR}.$((PATCH+1)) (PATCH — bug fixes only)"
fi

6. 更新更新日志文件

前置到现有的 CHANGELOG.md

# 如果 CHANGELOG.md 存在，将新条目前置
# 保留标题，在其后插入新版本

# 从现有文件中检测更新日志格式
head -20 CHANGELOG.md 2>/dev/null

更新规则

• 切勿覆盖 — 始终将新条目前置在顶部（标题下方）
• 保留现有条目 — 永不修改过去的版本
• 更新 [Unreleased] 部分 — 将未发布的项目移到新版本中
• 添加比较链接 — 更新底部的链接引用
• 匹配现有样式 — 使用与先前条目相同的格式

7. 平台特定的发布创建

GitHub 发布

# 创建标签
git tag -a v2.4.0 -m "Release v2.4.0"
git push origin v2.4.0

# 创建 GitHub 发布
gh release create v2.4.0 \
  --title "v2.4.0" \
  --notes-file release-notes.md \
  --latest

# 创建预发布版本
gh release create v2.4.0-beta.1 \
  --title "v2.4.0 Beta 1" \
  --notes-file release-notes.md \
  --prerelease

# 创建草稿发布以供审核
gh release create v2.4.0 \
  --title "v2.4.0" \
  --notes-file release-notes.md \
  --draft

GitLab 发布

# 创建标签和发布
glab release create v2.4.0 \
  --name "v2.4.0" \
  --notes "$(cat release-notes.md)"

npm 发布

# 更新 package.json 中的版本
npm version minor  # 或 major/patch
# 这将创建一个 git 标签并更新 package.json

# 发布
npm publish

PyPI 发布

# 更新 pyproject.toml 中的版本
# 构建并发布
python -m build
python -m twine upload dist/*

Cargo 发布（Rust）

# 更新 Cargo.toml 中的版本
cargo publish

8. 自动化与 CI 集成

用于自动更新日志的 GitHub Actions 工作流

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - 'v*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Generate changelog
        run: |
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
          git log ${PREV_TAG}..HEAD --oneline > changelog.txt
      - name: Create release
        uses: softprops/action-gh-release@v2
        with:
          body_path: changelog.txt

建议 CI 设置

如果不存在自动化更新日志，建议设置：

• 提交信息检查（commitlint + husky）
• CI 中的自动化更新日志生成
• 版本更新脚本
• 发布自动化

输出格式

将更新日志呈现为：

1. 发布摘要

Release: v2.4.0 (previous: v2.3.1)
Commits: 47 | PRs: 16 | Contributors: 8
Date range: 2026-01-28 → 2026-02-17
Version bump: MINOR (new features, no breaking changes)

2. 更新日志内容

完整格式化的更新日志，采用适当的格式。

3. 操作

• 更新 CHANGELOG.md（显示确切的编辑内容）
• 创建 git 标签
• 创建平台发布（GitHub/GitLab）
• 发布包（如果适用）

适应规则

• 检测更新日志格式 — 如果存在现有的 CHANGELOG.md，则匹配其样式
• 检测提交风格 — 如果使用约定式提交，则解析它们；否则分析差异
• 受众感知 — 对产品使用格式 B（面向用户），对库使用格式 A（保持更新日志），对内部工具使用格式 C（开发者）
• 处理无标签情况 — 如果不存在先前的标签，则使用初始提交作为起点
• 处理单体仓库 — 如果变更跨越多个包，则生成每个包的更新日志
• 尊重现有自动化 — 如果配置了 standard-version、semantic-release 或 changesets 等工具，则与其协作而非重复
• 包含迁移步骤 — 如果检测到破坏性变更，始终包含升级说明

总结

每次更新日志生成结束时，包含：

1. 建议版本 — 主版本号/次版本号/修订号及理由
2. 更新日志预览 — 已格式化、准备提交的内容
3. 破坏性变更 — 如果存在，单独高亮显示
4. 部署说明 — 运维人员需要了解的任何信息
5. 后续步骤 — 要运行的标签、发布、发布命令

每周安装次数

1

仓库

aakash-dhar/cla…e-skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykWarn

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

2. Gather Changes

Collect Commits

LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

# All commits since last tag with full message
git log ${LAST_TAG}..HEAD --format="COMMIT_START%nHash: %H%nShort: %h%nAuthor: %aN <%aE>%nDate: %ai%nSubject: %s%nBody: %b%nCOMMIT_END"

# One-line summary
git log ${LAST_TAG}..HEAD --oneline

# With file changes
git log ${LAST_TAG}..HEAD --oneline --name-status

# Diff stats
git diff --stat ${LAST_TAG}..HEAD

# Contributors
git log ${LAST_TAG}..HEAD --format='%aN' | sort | uniq -c | sort -rn

Collect Merged PRs (GitHub)

# List merged PRs since last tag date
LAST_TAG_DATE=$(git log -1 --format=%ci $(git describe --tags --abbrev=0 2>/dev/null) 2>/dev/null)

# Using gh CLI
gh pr list --state merged --search "merged:>=${LAST_TAG_DATE}" --json number,title,labels,author,body --limit 100

# Alternative: extract PR numbers from merge commits
git log ${LAST_TAG}..HEAD --oneline --grep="Merge pull request" | grep -oE "#[0-9]+"
git log ${LAST_TAG}..HEAD --oneline --grep="(#[0-9]+)" | grep -oE "#[0-9]+"

Collect Merged MRs (GitLab)

# Using glab CLI
glab mr list --state merged --json number,title,labels,author

3. Categorize Changes

Parse Conventional Commits

Classify commits based on their prefix:

If Commits Are NOT Conventional

When commits don't follow conventional format, analyze the diff to categorize:

# Analyze what areas changed
git diff --stat ${LAST_TAG}..HEAD | tail -1  # summary

# Group by directory/module
git diff --name-only ${LAST_TAG}..HEAD | sed 's|/.*||' | sort | uniq -c | sort -rn

# Look for keywords in commit messages
git log ${LAST_TAG}..HEAD --oneline | grep -iE "fix|bug|patch|resolve" # Bug fixes
git log ${LAST_TAG}..HEAD --oneline | grep -iE "add|new|feature|implement|support" # Features
git log ${LAST_TAG}..HEAD --oneline | grep -iE "remove|delete|deprecate|drop" # Removals
git log ${LAST_TAG}..HEAD --oneline | grep -iE "update|upgrade|bump|depend" # Dependencies
git log ${LAST_TAG}..HEAD --oneline | grep -iE "perf|speed|fast|optim|cache" # Performance
git log ${LAST_TAG}..HEAD --oneline | grep -iE "security|vuln|cve|auth" # Security
git log ${LAST_TAG}..HEAD --oneline | grep -iE "refactor|clean|restructure" # Refactoring
git log ${LAST_TAG}..HEAD --oneline | grep -iE "doc|readme|comment" # Docs
git log ${LAST_TAG}..HEAD --oneline | grep -iE "test|spec|coverage" # Testing
git log ${LAST_TAG}..HEAD --oneline | grep -iE "ci|pipeline|workflow|deploy" # CI/CD

Detect Breaking Changes

# Check commit bodies for BREAKING CHANGE
git log ${LAST_TAG}..HEAD --format="%B" | grep -i "BREAKING CHANGE"

# Check for removed exports/endpoints
git diff ${LAST_TAG}..HEAD -- "*.ts" "*.js" | grep -E "^-export|^-module\.exports"
git diff ${LAST_TAG}..HEAD -- "*.py" | grep -E "^-def |^-class "

# Check for removed API routes
git diff ${LAST_TAG}..HEAD -- "*route*" "*controller*" "*endpoint*" | grep "^-"

# Check for database migrations that drop/rename
find . -name "*.sql" -newer $(git rev-parse ${LAST_TAG}) | xargs grep -liE "DROP|RENAME|ALTER.*DROP" 2>/dev/null

# Check for changed config/env requirements
git diff ${LAST_TAG}..HEAD -- ".env.example" "*.config.*" "docker-compose.*"

4. Changelog Formats

Format A: Keep a Changelog (Recommended for Libraries/OSS)

Follows keepachangelog.com format:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [2.4.0] - 2026-02-17

### Added
- OAuth2 login support with Google and GitHub providers (#234)
- Real-time order status notifications via WebSocket (#241)
- Bulk export of analytics data in CSV and JSON formats (#238)
- Rate limiting on all public API endpoints (#245)

### Changed
- Upgraded Next.js from 14.2 to 15.1 (#250)
- Migrated email service from Mailgun to SendGrid (#247)
- Improved search indexing performance by 3x with batch processing (#243)

### Fixed
- Fixed duplicate charge on payment retry when Stripe webhook is delayed (#236)
- Fixed pagination returning wrong total count on filtered queries (#239)
- Fixed timezone handling in scheduled report generation (#242)
- Fixed memory leak in WebSocket connection handler (#248)

### Security
- Patched XSS vulnerability in user profile bio field (#237)
- Updated jsonwebtoken to 9.0.2 to fix CVE-2024-XXXXX (#246)

### Deprecated
- The `/api/v1/reports` endpoint is deprecated in favor of `/api/v2/analytics`. Will be removed in v3.0.0.

### Removed
- Removed legacy CSV import endpoint `/api/v1/import/csv` (use `/api/v2/import` instead)

## [2.3.1] - 2026-01-28

### Fixed
- ...

[Unreleased]: https://github.com/org/repo/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/org/repo/compare/v2.3.1...v2.4.0
[2.3.1]: https://github.com/org/repo/compare/v2.3.0...v2.3.1

Format B: User-Facing Release Notes (For Products/Apps)

Written for end users, not developers:

# What's New in v2.4.0 🚀

Released: February 17, 2026

## Highlights

### Sign in with Google and GitHub
You can now log in using your Google or GitHub account — no more passwords
to remember. Head to Settings → Account → Connected Accounts to link yours.

### Live Order Tracking
Watch your order status update in real time. No more refreshing the page —
you'll see status changes the moment they happen.

### Bulk Data Export
Export your analytics data in CSV or JSON format. Perfect for custom reports
or importing into your own tools. Find it under Analytics → Export.

## Improvements

- **Faster search**: Search results now load 3x faster, especially on large catalogs
- **Better emails**: We've moved to a more reliable email provider — fewer delays on order confirmations
- **API rate limits**: Added rate limiting to protect against abuse and ensure consistent performance

## Bug Fixes

- Fixed an issue where payments could be charged twice if your connection dropped during checkout
- Fixed incorrect page counts when filtering product lists
- Fixed scheduled reports showing wrong timezone for some regions
- Fixed a rare issue where the app could slow down after staying connected for a long time

## Security

- Fixed a text rendering issue in user profiles that could allow script injection
- Updated a security library to patch a known vulnerability

## Breaking Changes

⚠️ **API v1 Reports Endpoint Deprecated**
The `/api/v1/reports` endpoint is now deprecated. Please migrate to
`/api/v2/analytics` before July 2026 when v1 will be removed.
See our [migration guide](link) for details.

## Upgrade Notes

No action required for most users. If you use our API:
- Update any code using `/api/v1/import/csv` to `/api/v2/import`
- Add rate limit handling (429 responses) to your API clients

---

**Full Changelog**: [v2.3.1...v2.4.0](https://github.com/org/repo/compare/v2.3.1...v2.4.0)

Format C: Developer Release Notes (For Internal Teams)

Technical and detailed, for the engineering team:

# Release v2.4.0

**Date**: 2026-02-17
**Tag**: v2.4.0
**Commits**: 47 commits from 8 contributors
**PRs Merged**: 16

## Summary

This release adds OAuth2 authentication, real-time WebSocket notifications,
and bulk data export. Major infrastructure change: email migration from
Mailgun to SendGrid. Performance improvement on search indexing (3x faster).

## Breaking Changes

### API
- `DELETE /api/v1/import/csv` — Removed. Use `POST /api/v2/import` with `format: "csv"` header
- `GET /api/v1/reports` — Deprecated (still works). Returns `Sunset: 2026-07-01` header

### Database
- Migration `20260215_add_oauth_providers` adds `oauth_providers` table and `users.oauth_id` column
- Migration `20260216_add_websocket_sessions` adds `ws_sessions` table

### Environment Variables
- **New Required**: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
- **New Required**: `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
- **New Required**: `SENDGRID_API_KEY` (replaces `MAILGUN_API_KEY`)
- **Removed**: `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`

## Changes by Area

### Authentication (#234, #237)
- Added OAuth2 flow with PKCE for Google and GitHub
- New tables: `oauth_providers`, `oauth_tokens`
- Modified: `users` table (added `oauth_id`, `oauth_provider` columns)
- Patched XSS in profile bio (used DOMPurify for sanitization)
- Files: `src/services/auth/`, `src/api/routes/auth.ts`, `src/db/migrations/`

### Real-time Notifications (#241, #248)
- WebSocket server using `ws` library on `/ws` path
- Redis pub/sub for multi-instance broadcast
- Fixed connection leak (missing `close` event handler)
- Files: `src/services/websocket/`, `src/lib/redis-pubsub.ts`

### Data Export (#238)
- New endpoint: `POST /api/v2/analytics/export`
- Supports CSV and JSON output
- Streams results for large datasets (no memory issues)
- Files: `src/api/routes/analytics.ts`, `src/services/export/`

### Search Performance (#243)
- Batch indexing: 100 items per batch instead of 1-by-1
- Added Redis cache layer (5-minute TTL)
- Reduced average index time from 3.2s to 0.9s
- Files: `src/services/search/`, `src/lib/cache.ts`

### Email Migration (#247)
- Swapped Mailgun SDK for SendGrid v3
- Updated all email templates (same look, different template engine)
- Added email delivery webhooks for bounce tracking
- Files: `src/lib/email.ts`, `src/templates/email/`

### Infrastructure (#245, #246, #250)
- Added express-rate-limit: 100 req/min per IP on public endpoints
- Upgraded Next.js 14.2 → 15.1 (React 19, Server Actions stable)
- Updated jsonwebtoken 8.5.1 → 9.0.2 (CVE fix)

## Deployment Checklist

- [ ] Run database migrations (`npm run db:migrate`)
- [ ] Add new environment variables (see Breaking Changes)
- [ ] Remove old Mailgun env vars
- [ ] Verify SendGrid API key has correct permissions
- [ ] Verify OAuth callback URLs are registered with Google/GitHub
- [ ] Monitor WebSocket connections after deploy (new feature)
- [ ] Monitor email delivery rate (new provider)
- [ ] Verify rate limiting is not blocking legitimate traffic

## Rollback Plan

If issues arise:
1. Revert to v2.3.1 tag: `git checkout v2.3.1`
2. Run down migration: `npm run db:migrate:down -- --to 20260214`
3. Restore old env vars (MAILGUN_*)
4. Redeploy

## Contributors

- @alice — OAuth2 implementation, security fix
- @bob — WebSocket notifications, connection leak fix
- @carol — Data export, search performance
- @dave — Email migration, Next.js upgrade
- @eve — Rate limiting, dependency updates

## Stats

| Metric | Value |
|--------|-------|
| Commits | 47 |
| PRs merged | 16 |
| Files changed | 83 |
| Lines added | +3,241 |
| Lines removed | -1,087 |
| New tests | 34 |
| Contributors | 8 |

Format D: Compact Changelog (For Rapid Releases)

Short format for teams that release frequently:

## v2.4.0 (2026-02-17)

**Features**: OAuth2 login (Google/GitHub) (#234), real-time order notifications (#241), bulk data export (#238)
**Fixes**: Duplicate payment charge (#236), pagination count (#239), timezone in reports (#242), WebSocket memory leak (#248)
**Security**: XSS in profile bio (#237), jsonwebtoken CVE (#246)
**Performance**: Search indexing 3x faster (#243)
**Infrastructure**: Next.js 15.1 (#250), Mailgun → SendGrid (#247), API rate limiting (#245)
**Breaking**: Removed `/api/v1/import/csv`, deprecated `/api/v1/reports`
**New env vars**: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `SENDGRID_API_KEY`

5. Version Bump Suggestion

Semantic Versioning Rules

Based on the changes detected, suggest the appropriate version bump:

# Suggest version based on commits
HAS_BREAKING=$(git log ${LAST_TAG}..HEAD --format="%B" | grep -ci "BREAKING CHANGE\|breaking:")
HAS_FEAT=$(git log ${LAST_TAG}..HEAD --format="%s" | grep -ci "^feat")
HAS_FIX=$(git log ${LAST_TAG}..HEAD --format="%s" | grep -ci "^fix")

CURRENT=$(git describe --tags --abbrev=0 | sed 's/^v//')
MAJOR=$(echo $CURRENT | cut -d. -f1)
MINOR=$(echo $CURRENT | cut -d. -f2)
PATCH=$(echo $CURRENT | cut -d. -f3)

if [ "$HAS_BREAKING" -gt "0" ]; then
  echo "Suggested: v$((MAJOR+1)).0.0 (MAJOR — breaking changes detected)"
elif [ "$HAS_FEAT" -gt "0" ]; then
  echo "Suggested: v${MAJOR}.$((MINOR+1)).0 (MINOR — new features)"
else
  echo "Suggested: v${MAJOR}.${MINOR}.$((PATCH+1)) (PATCH — bug fixes only)"
fi

6. Updating the Changelog File

Prepend to Existing CHANGELOG.md

# If CHANGELOG.md exists, prepend the new entry
# Keep the header, insert new version after it

# Detect changelog format from existing file
head -20 CHANGELOG.md 2>/dev/null

Rules for Updating

• Never overwrite — always prepend new entries at the top (below header)
• Keep existing entries — never modify past versions
• Update [Unreleased] section — move unreleased items into the new version
• Add comparison links — update the link references at the bottom
• Match existing style — use the same format as previous entries

7. Platform-Specific Release Creation

GitHub Release

# Create tag
git tag -a v2.4.0 -m "Release v2.4.0"
git push origin v2.4.0

# Create GitHub release
gh release create v2.4.0 \
  --title "v2.4.0" \
  --notes-file release-notes.md \
  --latest

# Create as pre-release
gh release create v2.4.0-beta.1 \
  --title "v2.4.0 Beta 1" \
  --notes-file release-notes.md \
  --prerelease

# Create draft release for review
gh release create v2.4.0 \
  --title "v2.4.0" \
  --notes-file release-notes.md \
  --draft

GitLab Release

# Create tag and release
glab release create v2.4.0 \
  --name "v2.4.0" \
  --notes "$(cat release-notes.md)"

npm Publish

# Update version in package.json
npm version minor  # or major/patch
# This creates a git tag and updates package.json

# Publish
npm publish

PyPI Publish

# Update version in pyproject.toml
# Build and publish
python -m build
python -m twine upload dist/*

Cargo Publish (Rust)

# Update version in Cargo.toml
cargo publish

8. Automation & CI Integration

GitHub Actions Workflow for Auto-Changelog

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - 'v*'
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Generate changelog
        run: |
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
          git log ${PREV_TAG}..HEAD --oneline > changelog.txt
      - name: Create release
        uses: softprops/action-gh-release@v2
        with:
          body_path: changelog.txt

Suggest CI Setup

If no automated changelog exists, suggest setting up:

• Commit message linting (commitlint + husky)
• Automated changelog generation in CI
• Version bumping scripts
• Release automation

Output Format

Present the changelog as:

1. Release Summary

Release: v2.4.0 (previous: v2.3.1)
Commits: 47 | PRs: 16 | Contributors: 8
Date range: 2026-01-28 → 2026-02-17
Version bump: MINOR (new features, no breaking changes)

2. Changelog Content

The full formatted changelog in the appropriate format.

3. Actions

• Update CHANGELOG.md (show the exact edit)
• Create git tag
• Create platform release (GitHub/GitLab)
• Publish package (if applicable)

Adaptation Rules

• Detect changelog format — match the existing CHANGELOG.md style if one exists
• Detect commit style — if using conventional commits, parse them; otherwise analyze diffs
• Audience-aware — use Format B (user-facing) for products, Format A (keep-a-changelog) for libraries, Format C (developer) for internal tools
• Handle no tags — if no previous tags exist, use the initial commit as the starting point
• Handle monorepos — generate per-package changelogs if changes span multiple packages
• Respect existing automation — if tools like standard-version, semantic-release, or changesets are configured, work with them rather than duplicating
• Include migration steps — if breaking changes are detected, always include upgrade instructions

Summary

End every changelog generation with:

1. Suggested version — MAJOR/MINOR/PATCH with reasoning
2. Changelog preview — the formatted content ready to commit
3. Breaking changes — highlighted separately if any exist
4. Deployment notes — anything operators need to know
5. Next steps — tag, release, publish commands to run

Weekly Installs

1

Repository

aakash-dhar/cla…e-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1