mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 17:47:27 +00:00
📝 docs: update release changelog skills (#13899)
docs: add release changelog skills
This commit is contained in:
CanisMinor
GitHub
parent
c046d042f5
commit
29734eec23
4 changed files with 428 additions and 241 deletions
155
.agents/skills/docs-changelog/SKILL.md
Normal file
155
.agents/skills/docs-changelog/SKILL.md
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
---
|
||||
name: docs-changelog
|
||||
description: 'Writing guide for website changelog pages under docs/changelog/*.mdx. Use when creating or editing product update posts in EN/ZH. Not for GitHub Release notes.'
|
||||
---
|
||||
|
||||
# Docs Changelog Writing Guide
|
||||
|
||||
## Scope Boundary (Important)
|
||||
|
||||
This skill is only for changelog pages in:
|
||||
|
||||
- `docs/changelog/*.mdx`
|
||||
|
||||
This skill is **not** for GitHub Releases.\
|
||||
If the user asks for release PR body / GitHub Release notes, load `../version-release/SKILL.md`.
|
||||
|
||||
## Mandatory Companion Skills
|
||||
|
||||
For every docs changelog task, you MUST load:
|
||||
|
||||
- `../microcopy/SKILL.md`
|
||||
- `../i18n/SKILL.md` (when EN/ZH pair is involved)
|
||||
|
||||
## File and Naming Convention
|
||||
|
||||
Use date-based file names:
|
||||
|
||||
- English: `docs/changelog/YYYY-MM-DD-topic.mdx`
|
||||
- Chinese: `docs/changelog/YYYY-MM-DD-topic.zh-CN.mdx`
|
||||
|
||||
EN and ZH files must exist as a pair and describe the same release facts.
|
||||
|
||||
## Frontmatter Requirements
|
||||
|
||||
Each file should include:
|
||||
|
||||
```md
|
||||
---
|
||||
title: <Title>
|
||||
description: <1 sentence summary>
|
||||
tags:
|
||||
- <Tag 1>
|
||||
- <Tag 2>
|
||||
---
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `title` should match the H1 title in meaning.
|
||||
2. `description` should be concise and user-facing.
|
||||
3. `tags` should be feature-oriented, not internal-team labels.
|
||||
|
||||
## Content Structure (Recommended)
|
||||
|
||||
Use this shape unless the user requests otherwise:
|
||||
|
||||
1. `# <Title>`
|
||||
2. Opening paragraph (2-4 sentences): user-visible impact
|
||||
3. 1-3 capability sections (optional `##` headings)
|
||||
4. `## Improvements and fixes` / `## 体验优化与修复` with concise bullets
|
||||
|
||||
Keep heading count low and avoid heading-per-bullet structure.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
1. Keep all claims factual and tied to actual shipped changes.
|
||||
2. Explain user value first, implementation second.
|
||||
3. Prefer natural narrative paragraphs over pure bullet dumps.
|
||||
4. Avoid marketing exaggeration and vague adjectives.
|
||||
5. Keep internal terms consistent across EN/ZH files.
|
||||
6. Keep EN/ZH section order aligned and scope-aligned.
|
||||
|
||||
## EN/ZH Synchronization Rules
|
||||
|
||||
When generating bilingual changelogs:
|
||||
|
||||
1. Keep the same key facts in the same order.
|
||||
2. Localize naturally; do not do literal sentence-by-sentence translation.
|
||||
3. If one version has an `Improvements and fixes` bullet list, the other should have equivalent list intent.
|
||||
4. Do not introduce capabilities in only one language unless explicitly requested.
|
||||
|
||||
## Length Guidance
|
||||
|
||||
- Small update: 3-5 short paragraphs total
|
||||
- Medium update: 4-7 short paragraphs + concise fix bullets
|
||||
- Large update: 6-10 short paragraphs split into 2-4 sections
|
||||
|
||||
Do not pad content when changes are limited.
|
||||
|
||||
## Authoring Workflow
|
||||
|
||||
1. Collect source facts from PRs/commits/issues.
|
||||
2. Group changes by user workflow (not by internal module path).
|
||||
3. Draft EN and ZH versions with aligned structure.
|
||||
4. Verify terminology using `microcopy`/`i18n` guidance.
|
||||
5. Final pass: remove AI-like filler and tighten sentences.
|
||||
|
||||
## Docs Changelog Template (English)
|
||||
|
||||
```md
|
||||
---
|
||||
title: <Feature title>
|
||||
description: <One-sentence summary for users>
|
||||
tags:
|
||||
- <Tag A>
|
||||
- <Tag B>
|
||||
---
|
||||
|
||||
# <Feature title>
|
||||
|
||||
<Opening paragraph: what changed for users and why it matters.>
|
||||
|
||||
<Optional section paragraph for key capability 1.>
|
||||
|
||||
<Optional section paragraph for key capability 2.>
|
||||
|
||||
## Improvements and fixes
|
||||
|
||||
- <Fix or optimization 1>
|
||||
- <Fix or optimization 2>
|
||||
```
|
||||
|
||||
## Docs Changelog Template (Chinese)
|
||||
|
||||
```md
|
||||
---
|
||||
title: <功能标题>
|
||||
description: <一句话说明>
|
||||
tags:
|
||||
- <标签 A>
|
||||
- <标签 B>
|
||||
---
|
||||
|
||||
# <功能标题>
|
||||
|
||||
<开场段：这次更新给用户带来的直接变化。>
|
||||
|
||||
<可选能力段 1。>
|
||||
|
||||
<可选能力段 2。>
|
||||
|
||||
## 体验优化与修复
|
||||
|
||||
- <优化或修复 1>
|
||||
- <优化或修复 2>
|
||||
```
|
||||
|
||||
## Quick Checklist
|
||||
|
||||
- [ ] File path matches `docs/changelog` naming convention
|
||||
- [ ] EN and ZH versions both exist and match in facts
|
||||
- [ ] Opening paragraph explains user-facing outcome
|
||||
- [ ] Main body is narrative-first, not bullet-only
|
||||
- [ ] `Improvements and fixes` section is concise and concrete
|
||||
- [ ] No fabricated claims or unsupported scope
|
||||
|
|
@ -1,18 +1,27 @@
|
|||
---
|
||||
name: version-release
|
||||
description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. Provides guides for Minor Release and Patch Release workflows."
|
||||
description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. This skill is for release process and GitHub Release notes (not docs/changelog page writing)."
|
||||
---
|
||||
|
||||
# Version Release Workflow
|
||||
|
||||
## Scope Boundary (Important)
|
||||
|
||||
This skill is only for:
|
||||
|
||||
1. Release branch / PR workflow
|
||||
2. CI trigger constraints (`auto-tag-release.yml`)
|
||||
3. GitHub Release note writing
|
||||
|
||||
This skill is **not** for writing `docs/changelog/*.mdx`.\
|
||||
If the user asks for website changelog pages, load `../docs-changelog/SKILL.md`.
|
||||
|
||||
## Mandatory Companion Skill
|
||||
|
||||
For every `/version-release` execution, you MUST load and apply:
|
||||
|
||||
- `../microcopy/SKILL.md`
|
||||
|
||||
Changelog style guidance is now fully embedded in this skill. Keep release facts unchanged, and only improve structure, readability, and tone.
|
||||
|
||||
## Overview
|
||||
|
||||
The primary development branch is **canary**. All day-to-day development happens on canary. When releasing, canary is merged into main. After merge, `auto-tag-release.yml` automatically handles tagging, version bumping, creating a GitHub Release, and syncing back to the canary branch.
|
||||
|
|
@ -26,7 +35,7 @@ Only two release types are used in practice (major releases are extremely rare a
|
|||
|
||||
## Minor Release Workflow
|
||||
|
||||
Used to publish a new minor version (e.g. v2.2.0), roughly every 4 weeks.
|
||||
Used to publish a new minor version (e.g. `v2.2.0`), roughly every 4 weeks.
|
||||
|
||||
### Steps
|
||||
|
||||
|
|
@ -39,7 +48,7 @@ git checkout -b release/v{version}
|
|||
git push -u origin release/v{version}
|
||||
```
|
||||
|
||||
2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. 2.1.x → 2.2.0)
|
||||
2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. 2.1.x -> 2.2.0)
|
||||
|
||||
3. **Create a PR to main**
|
||||
|
||||
|
|
@ -51,9 +60,10 @@ gh pr create \
|
|||
--body "## 📦 Release v{version} ..."
|
||||
```
|
||||
|
||||
> \[!IMPORTANT]: The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.
|
||||
> \[!IMPORTANT]
|
||||
> The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.
|
||||
|
||||
4. **Automatic trigger after merge**: auto-tag-release detects the title format and uses the version number from the title to complete the release.
|
||||
4. **Automatic trigger after merge**: `auto-tag-release` detects the title format and uses the version number from the title to complete the release.
|
||||
|
||||
### Scripts
|
||||
|
||||
|
|
@ -68,7 +78,7 @@ Version number is automatically bumped by patch +1. There are 4 common scenarios
|
|||
|
||||
| Scenario | Source Branch | Branch Naming | Description |
|
||||
| ------------------- | ------------- | ----------------------------- | ------------------------------------------------ |
|
||||
| Weekly Release | canary | `release/weekly-{YYYYMMDD}` | Weekly release train, canary → main |
|
||||
| Weekly Release | canary | `release/weekly-{YYYYMMDD}` | Weekly release train, canary -> main |
|
||||
| Bug Hotfix | main | `hotfix/v{version}-{hash}` | Emergency bug fix |
|
||||
| New Model Launch | canary | Community PR merged directly | New model launch, triggered by PR title prefix |
|
||||
| DB Schema Migration | main | `release/db-migration-{name}` | Database migration, requires dedicated changelog |
|
||||
|
|
@ -81,19 +91,19 @@ All scenarios auto-bump patch +1. Patch PR titles do not need a version number.
|
|||
bun run hotfix:branch # Hotfix scenario
|
||||
```
|
||||
|
||||
## Auto-Release Trigger Rules (auto-tag-release.yml)
|
||||
## Auto-Release Trigger Rules (`auto-tag-release.yml`)
|
||||
|
||||
After a PR is merged into main, CI determines whether to release based on the following priority:
|
||||
|
||||
### 1. Minor Release (Exact Version)
|
||||
|
||||
PR title matches `🚀 release: v{x.y.z}` → uses the version number from the title.
|
||||
PR title matches `🚀 release: v{x.y.z}` -> uses the version number from the title.
|
||||
|
||||
### 2. Patch Release (Auto patch +1)
|
||||
|
||||
Triggered by the following priority:
|
||||
|
||||
- **Branch name match**: `hotfix/*` or `release/*` → triggers directly (skips title detection)
|
||||
- **Branch name match**: `hotfix/*` or `release/*` -> triggers directly (skips title detection)
|
||||
- **Title prefix match**: PRs with the following title prefixes will trigger:
|
||||
- `style` / `💄 style`
|
||||
- `feat` / `✨ feat`
|
||||
|
|
@ -104,241 +114,205 @@ Triggered by the following priority:
|
|||
|
||||
### 3. No Trigger
|
||||
|
||||
PRs that don't match any of the above conditions (e.g. `docs`, `chore`, `ci`, `test` prefixes) will not trigger a release when merged into main.
|
||||
PRs that don't match any conditions above (e.g. `docs`, `chore`, `ci`, `test`) will not trigger a release when merged into main.
|
||||
|
||||
## Post-Release Automated Actions
|
||||
|
||||
1. **Bump package.json** — commits `🔖 chore(release): release version v{x.y.z} [skip ci]`
|
||||
1. **Bump `package.json`** — commits `🔖 chore(release): release version v{x.y.z} [skip ci]`
|
||||
2. **Create annotated tag** — `v{x.y.z}`
|
||||
3. **Create GitHub Release**
|
||||
4. **Dispatch sync-main-to-canary** — syncs main back to the canary branch
|
||||
4. **Dispatch `sync-main-to-canary`** — syncs main back to canary
|
||||
|
||||
## Claude Action Guide
|
||||
## Agent Action Guide
|
||||
|
||||
When the user requests a release:
|
||||
|
||||
### Minor Release
|
||||
|
||||
1. Read `package.json` to get the current version and compute the next minor version
|
||||
2. Create a `release/v{version}` branch from canary
|
||||
3. Push and create a PR — **title must be `🚀 release: v{version}`**
|
||||
4. Inform the user that merging the PR will automatically trigger the release
|
||||
|
||||
### Precheck
|
||||
|
||||
Before creating the release branch, verify the source branch:
|
||||
|
||||
- **Weekly Release** (`release/weekly-*`): must branch from `canary`
|
||||
- **All other release/hotfix branches**: must branch from `main` — run `git merge-base --is-ancestor main <branch> && echo OK` to confirm
|
||||
- If the branch is based on the wrong source, delete and recreate from the correct base
|
||||
- **All other release/hotfix branches**: must branch from `main`; run `git merge-base --is-ancestor main <branch> && echo OK`
|
||||
- If the branch is based on the wrong source, recreate from the correct base
|
||||
|
||||
### Minor Release
|
||||
|
||||
1. Read `package.json` to get the current version and compute the next minor version
|
||||
2. Create a `release/v{version}` branch from canary
|
||||
3. Push and create PR — **title must be `🚀 release: v{version}`**
|
||||
4. Inform the user that merge will auto-trigger release
|
||||
|
||||
### Patch Release
|
||||
|
||||
Choose the appropriate workflow based on the scenario (see `reference/patch-release-scenarios.md`):
|
||||
Choose workflow by scenario (see `reference/patch-release-scenarios.md`):
|
||||
|
||||
- **Weekly Release**: Create a `release/weekly-{YYYYMMDD}` branch from canary, scan `git log main..canary` to write the changelog, title like `🚀 release: 20260222`
|
||||
- **Bug Hotfix**: Create a `hotfix/` branch from main, use a gitmoji prefix title (e.g. `🐛 fix: ...`)
|
||||
- **New Model Launch**: Community PRs trigger automatically via title prefix (`feat` / `style`), no extra steps needed
|
||||
- **DB Migration**: Create a `release/db-migration-{name}` branch from main, cherry-pick migration commits, write a dedicated migration changelog
|
||||
- **Weekly Release**: create `release/weekly-{YYYYMMDD}` from canary; use `git log main..canary` for release note inputs; title like `🚀 release: 20260222`
|
||||
- **Bug Hotfix**: create `hotfix/` from main; use gitmoji prefix title (e.g. `🐛 fix: ...`)
|
||||
- **New Model Launch**: community PRs trigger automatically via title prefix (`feat` / `style`)
|
||||
- **DB Migration**: create `release/db-migration-{name}` from main; cherry-pick migration commits; include dedicated migration notes
|
||||
|
||||
### Important Notes
|
||||
### Hard Rules
|
||||
|
||||
- **Do NOT manually modify the version in package.json** — CI will auto-bump it
|
||||
- **Do NOT manually create tags** — CI will create them automatically
|
||||
- The Minor Release PR title format is a hard requirement — incorrect format will not use the specified version number
|
||||
- Patch PRs do not need a version number — CI auto-bumps patch +1
|
||||
- All release PRs must include a user-facing changelog
|
||||
- **Do NOT** manually modify `package.json` version
|
||||
- **Do NOT** manually create tags
|
||||
- Minor PR title format is strict
|
||||
- Patch PRs do not need explicit version number
|
||||
- Keep release facts accurate; do not invent metrics or availability statements
|
||||
|
||||
## Changelog Writing Guidelines
|
||||
## GitHub Release Changelog Standard (Long-Form Style)
|
||||
|
||||
All release PR bodies (both Minor and Patch) must include a user-facing changelog. Scan changes via `git log main..canary --oneline` or `git diff main...canary --stat`, then write following the format below.
|
||||
Use this section for writing **GitHub Release notes** (or release PR body when the PR body is intended to become release notes).\
|
||||
Do not use this as `docs/changelog` page guidance.
|
||||
|
||||
### Format Reference
|
||||
### Positioning
|
||||
|
||||
- Weekly Release: See `reference/changelog-example/weekly-release.md`
|
||||
- DB Migration: See `reference/changelog-example/db-migration.md`
|
||||
This release-note style is:
|
||||
|
||||
### Mandatory Inputs Before Writing
|
||||
1. **Data-backed at the top** (date, range, key metrics)
|
||||
2. **Narrative first, then structured detail**
|
||||
3. **Deep but scannable** (clear sectioning + compact bullets)
|
||||
4. **Contributor-forward** (credits are part of the release story)
|
||||
|
||||
1. Release diff context (`git log main..canary` and/or `git diff main...canary --stat`)
|
||||
2. Existing release template constraints (title, credits, trigger rules)
|
||||
3. `../microcopy/SKILL.md` terminology constraints
|
||||
### Required Inputs Before Writing
|
||||
|
||||
### Output Constraints (Hard Rules)
|
||||
Collect these inputs first:
|
||||
|
||||
1. Keep all factual claims accurate to merged changes.
|
||||
2. Do not invent numbers, scope, timelines, or availability tiers.
|
||||
3. Keep release title and trigger-sensitive format unchanged.
|
||||
4. Keep `Credits` section intact (format required by project conventions).
|
||||
5. Prefer fewer headings and more natural narrative paragraphs.
|
||||
6. EN/ZH versions must cover the same facts in the same order.
|
||||
7. Prefer storytelling over feature enumeration.
|
||||
8. Avoid `Key Updates` sections that are only bullet dumps unless explicitly requested.
|
||||
1. Compare range (`<prev_tag>...<current_tag>`)
|
||||
2. Release metrics (commits, merged PRs, resolved issues, contributors, optional files/insertions/deletions)
|
||||
3. High-impact changes by domain (core loop, platform/gateway, UX, tooling, security, reliability)
|
||||
4. Contributor list (with standout contributions if known)
|
||||
5. Known risks / migrations / rollout notes (if any)
|
||||
|
||||
### Editorial Voice (Notion/Linear-Inspired)
|
||||
If metrics cannot be reliably computed, omit unknown numbers instead of guessing.
|
||||
|
||||
Target a changelog voice that is calm, confident, and human:
|
||||
### Canonical Structure
|
||||
|
||||
- Start from user reality, not internal implementation.
|
||||
- Explain why this change matters before listing mechanics.
|
||||
- Keep tone practical and grounded, but allow a little product warmth.
|
||||
- Favor concrete workflow examples over abstract claims.
|
||||
- Write like an update from a thoughtful product team, not a marketing launch page.
|
||||
Follow this section order unless the user asks otherwise:
|
||||
|
||||
### Writing Model (3-Pass Rewrite)
|
||||
1. `# 🚀 LobeHub v<x.y.z> (<YYYYMMDD>)`
|
||||
2. Metadata lines:
|
||||
- `Release Date`
|
||||
- `Since <Previous Version>` metrics
|
||||
3. One quoted release thesis (single paragraph, 1-2 lines)
|
||||
4. `## ✨ Highlights` (6-12 bullets for major releases; 3-8 for weekly)
|
||||
5. Domain blocks with optional `###` subsections:
|
||||
- `## 🏗️ Core Agent & Architecture` (or equivalent product core)
|
||||
- `## 📱 Platforms / Integrations`
|
||||
- `## 🖥️ CLI & User Experience`
|
||||
- `## 🔧 Tooling`
|
||||
- `## 🔒 Security & Reliability`
|
||||
- `## 📚 Documentation` (optional if meaningful)
|
||||
6. `## 👥 Contributors`
|
||||
7. `**Full Changelog**: <prev>...<current>`
|
||||
|
||||
#### Pass 1: Remove AI Vocabulary and Filler
|
||||
Use `---` separators between major blocks for long releases.
|
||||
|
||||
- Replace inflated words with simple alternatives.
|
||||
- Remove transition padding like "furthermore", "notably", "it is worth noting that".
|
||||
- Cut generic importance inflation ("pivotal", "testament", "game-changer").
|
||||
- Prefer direct verbs like `run`, `customize`, `manage`, `capture`, `improve`, `fix`.
|
||||
### Writing Rules (Hard)
|
||||
|
||||
#### Pass 2: Break AI Sentence Patterns
|
||||
1. **No fabricated metrics**: all numbers must be traceable.
|
||||
2. **No vague headline bullets**: each bullet must include capability + impact.
|
||||
3. **No internal-only framing**: phrase from user/operator perspective.
|
||||
4. **Security must be explicit** when security-sensitive fixes are present.
|
||||
5. **PR/issue linkage**: use `(#1234)` when IDs are available.
|
||||
6. **Terminology consistency**: same feature/provider name across sections.
|
||||
7. **Do not bury migration or breaking changes**: elevate to dedicated section or callout.
|
||||
|
||||
Avoid these structures:
|
||||
### Style Rules (Long-Form)
|
||||
|
||||
- Parallel negation: "Not X, but Y"
|
||||
- Tricolon overload: "A, B, and C" used repeatedly
|
||||
- Rhetorical Q + answer: "What does this mean? It means..."
|
||||
- Dramatic reveal openers: "Here's the thing", "The result?"
|
||||
- Mirror symmetry in consecutive lines
|
||||
- Overuse of em dashes
|
||||
- Every paragraph ending in tidy "lesson learned" phrasing
|
||||
1. Start with an "everyday use" framing, not implementation internals.
|
||||
2. Mix narrative sentence + evidence bullets.
|
||||
3. Keep bullets compact but informative:
|
||||
- Good: `**Fast Mode (`/fast`)** — Priority routing for OpenAI and Anthropic, reducing latency on supported models. (#6875, #6960)`
|
||||
4. Use bold only for capability names, not for whole sentences.
|
||||
5. Keep heading depth <= 3 levels.
|
||||
|
||||
#### Pass 3: Add Human Product Texture
|
||||
### Release Size Heuristics
|
||||
|
||||
- Lead with user-visible outcome, then explain mechanism.
|
||||
- Mix sentence lengths naturally.
|
||||
- Prefer straightforward phrasing over polished-but-empty language.
|
||||
- Keep confidence, but avoid launch-ad hype.
|
||||
- Write like a product team update, not a marketing page.
|
||||
- **Minor / major milestone release**
|
||||
- Include full structure with multiple domain blocks.
|
||||
- `Highlights` usually 8-12 bullets.
|
||||
- **Weekly patch release**
|
||||
- Keep full skeleton but reduce subsection count.
|
||||
- `Highlights` usually 4-8 bullets.
|
||||
- **DB migration release**
|
||||
- Keep concise.
|
||||
- Must include `Migration overview`, operator impact, and rollback/backup note.
|
||||
|
||||
### Recommended Structure Blueprint
|
||||
|
||||
Use this shape unless the user asks otherwise:
|
||||
|
||||
1. `# 🚀 release: ...`
|
||||
2. One opening paragraph (2-4 sentences) that explains overall user impact.
|
||||
3. 2-4 narrative capability blocks (short headings optional):
|
||||
- each block = user value + key capability
|
||||
4. `Improvements and fixes` / `体验优化与修复` with concise bullets
|
||||
5. `Credits` with required mention format
|
||||
|
||||
### Length and Reading Density (Important)
|
||||
|
||||
Avoid overly short release notes when the diff is substantial.
|
||||
|
||||
- Weekly release PR body:
|
||||
- Usually target 350-700 English words (or equivalent Chinese length)
|
||||
- Keep 2-4 narrative sections, each with at least one real paragraph
|
||||
- Minor release PR body:
|
||||
- Usually target 500-1000 English words (or equivalent Chinese length)
|
||||
- Allow richer context and more concrete usage scenarios
|
||||
- DB migration release PR body:
|
||||
- Keep concise, but still include context + impact + operator notes
|
||||
- If there are many commits, increase narrative depth before adding more bullets.
|
||||
- If there are few commits, stay concise and do not pad content.
|
||||
|
||||
### Storytelling Contract (Major Capabilities)
|
||||
|
||||
For each major capability, write in this order:
|
||||
|
||||
1. Prior context/problem (briefly)
|
||||
2. What changed in this release
|
||||
3. Practical impact on user workflow
|
||||
|
||||
Do not collapse major capability sections into one-line bullets.
|
||||
|
||||
### Section Anatomy (Preferred)
|
||||
|
||||
Each major section should follow this internal rhythm:
|
||||
|
||||
1. Lead sentence: what changed and who benefits.
|
||||
2. Context sentence: what was painful, slow, or fragmented before.
|
||||
3. Mechanism paragraph: how the new behavior works in practice.
|
||||
4. Optional utility list (`Use X to:`) for actionable workflows.
|
||||
5. Optional availability closer when plan/platform constraints matter.
|
||||
|
||||
This pattern increases readability and makes changelogs more enjoyable to read without sacrificing precision.
|
||||
|
||||
### Section and Heading Heuristics
|
||||
|
||||
- Keep heading count low (typically 3-5).
|
||||
- Weekly release PR body target:
|
||||
- 1 opening paragraph
|
||||
- 2-4 major narrative sections
|
||||
- 1 improvements/fixes section
|
||||
- 1 credits section
|
||||
- Never produce heading-per-bullet layout.
|
||||
- If a section has 4+ bullets, convert into 2-3 short narrative paragraphs when possible.
|
||||
|
||||
### Linear-Style Block Pattern
|
||||
|
||||
Use this pattern when writing major sections:
|
||||
### GitHub Release Changelog Template
|
||||
|
||||
```md
|
||||
## <Capability name>
|
||||
# 🚀 LobeHub v<x.y.z> (<YYYYMMDD>)
|
||||
|
||||
<One sentence: what users can do now and why it matters.>
|
||||
**Release Date:** <Month DD, YYYY>
|
||||
**Since <Previous Version>:** <N commits> · <N merged PRs> · <N resolved issues> · <N contributors>
|
||||
|
||||
<One short paragraph: how this works in practice, in plain language.>
|
||||
> <One release thesis sentence: what this release unlocks in practice.>
|
||||
|
||||
<Optional list for workflows>
|
||||
Use <feature> to:
|
||||
- <practical action 1>
|
||||
- <practical action 2>
|
||||
- <practical action 3>
|
||||
---
|
||||
|
||||
<Optional availability sentence>
|
||||
## ✨ Highlights
|
||||
|
||||
- **<Capability A>** — <What changed and why it matters>. (#1234)
|
||||
- **<Capability B>** — <What changed and why it matters>. (#2345)
|
||||
- **<Capability C>** — <What changed and why it matters>. (#3456)
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Core Product & Architecture
|
||||
|
||||
### <Subdomain>
|
||||
|
||||
- <Concrete change + impact>. (#...)
|
||||
- <Concrete change + impact>. (#...)
|
||||
|
||||
---
|
||||
|
||||
## 📱 Platforms / Integrations
|
||||
|
||||
- <Platform update + impact>. (#...)
|
||||
- <Compatibility/reliability fix + impact>. (#...)
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ CLI & User Experience
|
||||
|
||||
- <User-facing workflow improvement>. (#...)
|
||||
- <Quality-of-life fix>. (#...)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Tooling
|
||||
|
||||
- <Tool/runtime improvement>. (#...)
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security & Reliability
|
||||
|
||||
- **Security:** <hardening or vulnerability fix>. (#...)
|
||||
- **Reliability:** <stability/performance behavior improvement>. (#...)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Contributors
|
||||
|
||||
**<N merged PRs>** from **<N contributors>** across **<N commits>**.
|
||||
|
||||
### Community Contributors
|
||||
|
||||
- @<username> - <notable contribution area>
|
||||
- @<username> - <notable contribution area>
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: <previous_tag>...<current_tag>
|
||||
```
|
||||
|
||||
### Notion-Style Readability Moves
|
||||
|
||||
Apply these moves when appropriate:
|
||||
|
||||
- Use one clear "scene" sentence to ground context (for example, what a team is doing when the feature helps).
|
||||
- Alternate paragraph lengths: one compact paragraph followed by a denser explanatory one.
|
||||
- Prefer specific nouns (`triage inbox`, `topic switch`, `mobile session`) over broad terms like "experience" or "workflow improvements".
|
||||
- Keep transitions natural (`Previously`, `Now`, `In practice`, `This means`) and avoid ornate writing.
|
||||
- End key sections with a practical takeaway sentence, not a slogan.
|
||||
|
||||
### Anti-Pattern Red Flags (Rewrite Required)
|
||||
|
||||
- "Key Updates" followed by only bullets and no narrative context
|
||||
- One bullet per feature with no prior context or user impact
|
||||
- Repeated template like "Feature X: did Y"
|
||||
- Heading-per-feature with no explanatory paragraph
|
||||
- Mechanical transitions with no causal flow
|
||||
|
||||
### EN/ZH Synchronization Rules
|
||||
|
||||
- Keep section order aligned.
|
||||
- Keep facts and scope aligned.
|
||||
- Localize naturally; avoid literal sentence mirroring.
|
||||
- If one language uses bullets for a section, the other should match style intent.
|
||||
|
||||
### Writing Tips
|
||||
|
||||
- **User-facing**: Describe changes that users can perceive, not internal implementation details
|
||||
- **Clear categories**: Group by features, models/providers, desktop, stability/fixes, etc.
|
||||
- **Highlight key items**: Use `**bold**` for important feature names
|
||||
- **Credit contributors**: Collect all committers via `git log` and list alphabetically
|
||||
- **Flexible categories**: Choose categories based on actual changes — no need to force-fit all categories
|
||||
- **Terminology enforcement**: Ensure wording follows `microcopy` skill terminology and tone constraints
|
||||
- **Linear narrative enforcement**: Follow capability -> explanation -> optional "Use X to" list
|
||||
- **Storytelling enforcement**: For major updates, write in "before -> now -> impact" order
|
||||
- **Depth enforcement**: If the diff is non-trivial, prefer complete paragraphs over compressed bullet-only summaries
|
||||
- **Pleasure-to-read enforcement**: Include concrete examples and practical scenarios so readers can imagine using the capability
|
||||
|
||||
### Quick Checklist
|
||||
|
||||
- [ ] First paragraph explains user-visible release outcome
|
||||
- [ ] Heading count is minimal and meaningful
|
||||
- [ ] Major capabilities are short narrative paragraphs, not only bullets
|
||||
- [ ] Includes "before -> now -> impact" for major sections
|
||||
- [ ] No obvious AI patterns (parallel negation, rhetorical Q/A, dramatic reveal)
|
||||
- [ ] Vocabulary is plain, direct, and product-credible
|
||||
- [ ] Improvements/fixes remain concise and scannable
|
||||
- [ ] Credits format is preserved exactly
|
||||
- [ ] EN/ZH versions align in facts and order
|
||||
- [ ] Uses top metadata and a clear release thesis
|
||||
- [ ] Includes `Highlights` plus domain-grouped sections
|
||||
- [ ] Every major bullet states both change and user/operator impact
|
||||
- [ ] Security and reliability updates are explicitly surfaced (when present)
|
||||
- [ ] Contributor credits and compare range are included
|
||||
- [ ] All numbers and claims are verifiable
|
||||
|
|
|
|||
|
|
@ -1,31 +1,60 @@
|
|||
# DB Schema Migration Changelog Example
|
||||
# 🚀 LobeHub v2.1.50 (20260416)
|
||||
|
||||
A changelog reference for database migration release PR bodies.
|
||||
**Release Date:** April 20, 2026\
|
||||
**Migration Scope:** Agent benchmark data model bootstrap (5 new tables, 2 new indexes)
|
||||
|
||||
> This release introduces a schema foundation for benchmark execution and reporting, so agent evaluation data is stored as a complete lifecycle instead of fragmented records.
|
||||
|
||||
---
|
||||
|
||||
This release includes a **database schema migration** for Agent Evaluation Benchmark. We are adding **5 new tables** so benchmark setup, runs, and run-topic records can be stored in a complete and queryable structure.
|
||||
## ✨ Highlights
|
||||
|
||||
## Migration overview
|
||||
- **Benchmark Lifecycle Schema** — Added a relational model that tracks benchmark setup, runs, per-topic execution, and record outputs end-to-end.
|
||||
- **Queryability Upgrade** — Added indexes for run status and benchmark-topic joins, improving operational queries in dashboard and debugging workflows.
|
||||
- **Safer Operator Rollout** — Migration is startup-driven and backward-compatible with existing non-benchmark chat workflows.
|
||||
|
||||
Previously, benchmark-related data lacked a full lifecycle model, which made it harder to track evaluation flow from dataset to run results. This migration introduces the missing relational layer so benchmark configuration, execution, and analysis records stay connected.
|
||||
---
|
||||
|
||||
In practical terms, this reduces ambiguity for downstream features and gives operators a cleaner foundation for troubleshooting and reporting.
|
||||
## 🗄️ Migration Overview
|
||||
|
||||
Added tables:
|
||||
|
||||
- `agent_eval_benchmarks`
|
||||
- `agent_eval_datasets`
|
||||
- `agent_eval_records`
|
||||
- `agent_eval_runs`
|
||||
- `agent_eval_run_topics`
|
||||
- `agent_eval_records`
|
||||
|
||||
## Notes for self-hosted users
|
||||
Added indexes:
|
||||
|
||||
- Migration runs automatically during app startup.
|
||||
- No manual SQL action is required in standard deployments.
|
||||
- As with any schema release, we still recommend database backup and rollout during a low-traffic window.
|
||||
- `idx_agent_eval_runs_status_created_at`
|
||||
- `idx_agent_eval_run_topics_run_id_topic_id`
|
||||
|
||||
The migration owner: @{pr-author} — responsible for this database schema change, reach out for any migration-related issues.
|
||||
These additions close a previous gap where benchmark data existed in partial forms but lacked a stable relational backbone for auditing and historical analysis.
|
||||
|
||||
> **Note for Claude**: Replace `{pr-author}` with the actual PR author. Retrieve via `gh pr view <number> --json author --jq '.author.login'` or `git log` commit author. Do NOT hardcode a username.
|
||||
---
|
||||
|
||||
## ⚙️ Operator Notes
|
||||
|
||||
- Migration runs automatically on application startup.
|
||||
- No manual SQL is required in standard deployment paths.
|
||||
- Schedule rollout in a low-traffic window and take a backup snapshot before deployment.
|
||||
- If migration fails, do not retry repeatedly; inspect migration logs and lock state first.
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Reliability & Risk
|
||||
|
||||
- Existing chat/session paths are unaffected unless benchmark features are enabled.
|
||||
- Migration is additive (new tables/indexes only), minimizing downgrade risk to existing entities.
|
||||
- Rollback should follow your standard DB restore or migration rollback policy if your environment requires strict reversibility.
|
||||
|
||||
---
|
||||
|
||||
## 👥 Owner
|
||||
|
||||
Migration owner: @{pr-author}
|
||||
|
||||
The migration owner is responsible for rollout follow-up and incident handling for this schema change.
|
||||
|
||||
> **Note for Claude**: Replace `{pr-author}` with the actual PR author. Retrieve via `gh pr view <number> --json author --jq '.author.login'` or from commit metadata. Do not hardcode a username.
|
||||
|
|
|
|||
|
|
@ -1,51 +1,80 @@
|
|||
# Patch Release (Weekly) Changelog Example
|
||||
# 🚀 LobeHub v2.1.50 (20260420)
|
||||
|
||||
A real-world changelog reference for weekly patch release PR bodies.
|
||||
**Release Date:** April 20, 2026\
|
||||
**Since v2026.04.13:** 96 commits · 58 merged PRs · 31 resolved issues · 17 contributors
|
||||
|
||||
> This weekly release focuses on reducing friction in everyday agent work: faster model routing, smoother gateway behavior, stronger task continuity, and clearer operator diagnostics when something goes wrong.
|
||||
|
||||
---
|
||||
|
||||
This weekly release includes **82 commits**. The throughline is simple: less friction when moving from idea to execution. Across agent workflows, model coverage, and desktop polish, this release removes several small blockers that used to interrupt momentum.
|
||||
## ✨ Highlights
|
||||
|
||||
The result is not one headline feature, but a noticeably smoother week-to-week experience. Teams can evaluate agents with clearer structure, ship richer media flows, and spend less time debugging provider and platform edge cases.
|
||||
- **Gateway Session Recovery** — Agent sessions now recover more reliably after short network interruptions, so long-running tasks continue with less manual retry. (#10121, #10133)
|
||||
- **Fast Model Routing** — Expanded low-latency routing for priority model tiers, reducing wait time in high-frequency generation workflows. (#10102, #10117)
|
||||
- **Agent Task Workspace** — Running tasks now remain isolated from main chat state, which keeps primary conversations cleaner while background work progresses. (#10088)
|
||||
- **Provider Coverage Update** — Added support for new model variants across OpenAI-compatible and regional providers, improving fallback options in production. (#10094, #10109)
|
||||
- **Desktop Attachment Flow** — File and screenshot attachment behavior is more predictable in desktop sessions, especially for mixed text + media prompts. (#10073)
|
||||
- **Security Hardening Pass** — Closed multiple input validation gaps in webhook and file-path handling paths. (#10141, #10152)
|
||||
|
||||
## Agent workflows and media generation
|
||||
---
|
||||
|
||||
Previously, some agent evaluation and media generation flows still felt fragmented: setup was manual, discoverability was uneven, and switching between topics could interrupt context. This release adds **Agent Benchmark** support and lands the **video generation** path end-to-end, from entry point to generation feedback.
|
||||
## 🏗️ Core Agent & Architecture
|
||||
|
||||
In practice, this means users can discover and run these workflows with fewer detours. Sidebar "new" indicators improve visibility, skeleton loading makes topic switches feel less abrupt, and memory-related controls now behave more predictably under real workload pressure.
|
||||
### Agent loop and context handling
|
||||
|
||||
We also expanded memory controls with effort and tool-permission configuration, and improved timeout calculation for memory analysis tasks so longer runs fail less often in production-like usage.
|
||||
- Improved context compaction thresholds to reduce mid-task exits under tight token budgets. (#10079)
|
||||
- Added better diagnostics for tool-call truncation and recovery behavior during streamed responses. (#10106)
|
||||
- Refined delegate task activity propagation to improve parent-child task status consistency. (#10098)
|
||||
|
||||
## Models and provider coverage
|
||||
### Provider and model behavior
|
||||
|
||||
Provider diversity matters most when teams can adopt new models without rewriting glue code every sprint. This release adds **Straico** and updates support for Claude Sonnet 4.6, Gemini 3.1 Pro Preview, Qwen3.5, Grok Imagine (`grok-imagine-image`), and MiniMax 2.5.
|
||||
- Unified provider-side timeout handling in fallback chains to reduce false failure classification. (#10097)
|
||||
- Updated reasoning-model defaults and response normalization for better cross-provider consistency. (#10109)
|
||||
|
||||
Use these updates to:
|
||||
---
|
||||
|
||||
- route requests to newly available providers
|
||||
- test newer model families without custom patching
|
||||
- keep model parameters and related i18n copy aligned across providers
|
||||
## 📱 Gateway & Platform Integrations
|
||||
|
||||
This keeps model exploration practical: faster evaluation loops, fewer adaptation surprises, and cleaner cross-provider behavior.
|
||||
- Gateway now drains in-flight events more safely before restart, reducing duplicate notification bursts. (#10125)
|
||||
- Discord and Slack adapters received retry/backoff tuning for unstable webhook windows. (#10091, #10119)
|
||||
- WeCom callback-mode message state persistence now uses safer atomic updates. (#10114)
|
||||
|
||||
## Desktop and platform polish
|
||||
---
|
||||
|
||||
Desktop receives a set of quality-of-life upgrades that reduce "death by a thousand cuts" moments. We integrated `electron-liquid-glass` for macOS Tahoe and improved DMG background assets and packaging flow for more consistent release output.
|
||||
## 🖥️ CLI & User Experience
|
||||
|
||||
The desktop editor now supports image upload from the file picker, which shortens everyday authoring steps and removes one more reason to switch tools mid-task.
|
||||
- Improved slash command discoverability in CLI and gateway contexts with clearer hint messages. (#10086)
|
||||
- `/model` switching feedback now returns clearer success/failure states in cross-platform chats. (#10108)
|
||||
- Setup flow now warns earlier about missing provider credentials in first-run scenarios. (#10115)
|
||||
|
||||
## Improvements and fixes
|
||||
---
|
||||
|
||||
- Fixed multiple video pipeline issues across precharge refund handling, webhook token verification, pricing parameter usage, asset cleanup, and type safety.
|
||||
- Fixed path traversal risk in `sanitizeFileName` and added corresponding unit tests.
|
||||
- Fixed MCP media URL generation when `APP_URL` was duplicated in output paths.
|
||||
- Fixed Qwen3 embedding failures caused by batch-size limits.
|
||||
- Fixed several UI interaction issues, including mobile header agent selector/topic count, ChatInput scrolling behavior, and tooltip stacking context.
|
||||
- Fixed missing `@napi-rs/canvas` native bindings in Docker standalone builds.
|
||||
- Improved GitHub Copilot authentication retry behavior and response error handling in edge cases.
|
||||
## 🔧 Tooling
|
||||
|
||||
## Credits
|
||||
- MCP registration flow now validates duplicate tool names before activation, reducing runtime conflicts. (#10093)
|
||||
- Browser tooling improved stale-session cleanup to prevent orphaned local resources. (#10112)
|
||||
|
||||
Huge thanks to these contributors (alphabetical):
|
||||
---
|
||||
|
||||
@AmAzing129 @Coooolfan @Innei @ONLY-yours @Zhouguanyang @arvinxx @eaten-cake @hezhijie0327 @nekomeowww @rdmclin2 @rivertwilight @sxjeru @tjx666
|
||||
## 🔒 Security & Reliability
|
||||
|
||||
- **Security:** Hardened path sanitization for uploaded assets and webhook callback validation. (#10141, #10152)
|
||||
- **Reliability:** Reduced empty-response retry storms by refining retry-classification conditions. (#10130)
|
||||
- **Reliability:** Improved timeout defaults for long-running background processes in constrained environments. (#10122)
|
||||
|
||||
---
|
||||
|
||||
## 👥 Contributors
|
||||
|
||||
**58 merged PRs** from **17 contributors** across **96 commits**.
|
||||
|
||||
### Community Contributors
|
||||
|
||||
- @alice-example - Gateway recovery and retry improvements
|
||||
- @bob-example - Provider fallback normalization
|
||||
- @charlie-example - Desktop media attachment flow
|
||||
- @dora-example - Webhook validation hardening
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: v2026.04.13...v2026.04.20
|
||||
|
|
|
|||
Loading…
Reference in a new issue