Back to Details

create-release-tags

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

create-release-tags

create-release-tags

Overview

概述

Automates Debian package version releases by updating 
debian/changelog
and 
linglong.yaml
(if present), generating change summaries from git log, and creating version commits.
通过更新
debian/changelog
和
linglong.yaml
（如果存在）、从Git日志生成变更摘要并创建版本提交，实现Debian包版本发布的自动化。

When to Use

适用场景

dot
digraph when_to_use {
    "Need to release version?" [shape=diamond];
    "Debian project?" [shape=diamond];
    "Use this skill" [shape=box];
    "Wrong tool" [shape=box];

    "Need to release version?" -> "Debian project?" [label="yes"];
    "Debian project?" -> "Use this skill" [label="yes"];
    "Debian project?" -> "Wrong tool" [label="no"];
}
Use when:
  • Releasing new version for Debian-based projects
  • Preparing test releases (tag prepare-test)
  • Bumping version numbers with changelog updates
  • Projects with or without linglong.yaml
Trigger phrases:
  • "tag release <version>"
  • "tag release" (auto-increment)
  • "tag prepare-test <version>"
  • "release new version"
  • "bump version"
  • "update version"
  • "prepare for release"
  • "prepare for testing"
Do NOT use when:
  • Projects without debian/changelog
  • Creating git tags (this skill only commits changes)
  • Non-Debian projects
dot
digraph when_to_use {
    "Need to release version?" [shape=diamond];
    "Debian project?" [shape=diamond];
    "Use this skill" [shape=box];
    "Wrong tool" [shape=box];

    "Need to release version?" -> "Debian project?" [label="yes"];
    "Debian project?" -> "Use this skill" [label="yes"];
    "Debian project?" -> "Wrong tool" [label="no"];
}
适用场景：
  • 为基于Debian的项目发布新版本
  • 准备测试版本（标签prepare-test）
  • 更新版本号并同步更新变更日志
  • 包含或不包含linglong.yaml的项目
触发短语：
  • "tag release <version>"
  • "tag release"（自动递增版本）
  • "tag prepare-test <version>"
  • "release new version"
  • "bump version"
  • "update version"
  • "prepare for release"
  • "prepare for testing"
请勿使用场景：
  • 没有debian/changelog的项目
  • 创建Git标签（本技能仅提交变更）
  • 非Debian项目

Quick Reference

快速参考

OperationCommandBehavior
Release specific version
tag release 1.2.3
Updates to specified version
Auto-increment patch
tag release
Increments patch (1.2.2 → 1.2.3)
Prepare test version
tag prepare-test 1.2.3
Updates for testing phase
操作命令行为
发布指定版本
tag release 1.2.3
更新至指定版本
自动递增补丁版本
tag release
递增补丁版本（1.2.2 → 1.2.3）
准备测试版本
tag prepare-test 1.2.3
为测试阶段更新版本

Implementation

实现步骤

Step 1: Detect Project Type

步骤1：检测项目类型

bash
undefined
bash
undefined

Check required files

Check required files

if [ ! -f debian/changelog ]; then echo "Error: Not a Debian project (debian/changelog not found)" exit 1 fi
if [ ! -f debian/changelog ]; then echo "Error: Not a Debian project (debian/changelog not found)" exit 1 fi

Check for linglong.yaml files

Check for linglong.yaml files

LINGLONG_FILES=$(find . -name "linglong.yaml" -type f) HAS_LINGLONG=1 if [ -z "$LINGLONG_FILES" ]; then HAS_LINGLONG=0 fi
undefined
LINGLONG_FILES=$(find . -name "linglong.yaml" -type f) HAS_LINGLONG=1 if [ -z "$LINGLONG_FILES" ]; then HAS_LINGLONG=0 fi
undefined

Step 2: Determine Target Version

步骤2：确定目标版本

Default behavior: If no version specified, auto-increment patch version (e.g., 6.5.26 → 6.5.27)
If version specified:
bash
TARGET_VERSION="$1"  # e.g., 6.5.47
If auto-increment (no version specified):
bash
undefined
默认行为：如果未指定版本，自动递增补丁版本（例如：6.5.26 → 6.5.27）
如果指定了版本：
bash
TARGET_VERSION="$1"  # e.g., 6.5.47
如果自动递增（未指定版本）：
bash
undefined

Extract current version from changelog

Extract current version from changelog

CURRENT_VERSION=$(head -1 debian/changelog | sed -n 's/.((.)).*/\1/p')
CURRENT_VERSION=$(head -1 debian/changelog | sed -n 's/.((.)).*/\1/p')

Extract and increment patch version (only increments patch: X.Y.Z → X.Y.Z+1)

Extract and increment patch version (only increments patch: X.Y.Z → X.Y.Z+1)

MAJOR=$(echo $CURRENT_VERSION | cut -d. -f1) MINOR=$(echo $CURRENT_VERSION | cut -d. -f2) PATCH=$(echo $CURRENT_VERSION | cut -d. -f3) TARGET_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
undefined
MAJOR=$(echo $CURRENT_VERSION | cut -d. -f1) MINOR=$(echo $CURRENT_VERSION | cut -d. -f2) PATCH=$(echo $CURRENT_VERSION | cut -d. -f3) TARGET_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
undefined

Step 3: Generate Change Summary

步骤3：生成变更摘要

IMPORTANT: Get commits from current changelog version (NOT from git tags, as tags may not always be created).
bash
undefined
重要提示：从当前变更日志版本获取提交记录（不要使用Git标签，因为并非所有版本都有对应的Git标签）。
bash
undefined

Extract date from first author line in changelog

Extract date from first author line in changelog

Format: "Mon, 05 Jan 2026 15:29:58 +0800"

Format: "Mon, 05 Jan 2026 15:29:58 +0800"

This finds the line starting with " -- " and extracts the date part

This finds the line starting with " -- " and extracts the date part

CURRENT_DATE=$(grep -m1 "^ -- " debian/changelog | sed 's/.* //')
CURRENT_DATE=$(grep -m1 "^ -- " debian/changelog | sed 's/.* //')

Get commit titles since that date (note: two spaces before *)

Get commit titles since that date (note: two spaces before *)

if [ -n "$CURRENT_DATE" ]; then CHANGES=$(git log --since="${CURRENT_DATE}" --pretty=format:" * %s") else # Fallback: get recent commits if date extraction fails CHANGES=$(git log --pretty=format:" * %s" -10) fi
if [ -n "$CURRENT_DATE" ]; then CHANGES=$(git log --since="${CURRENT_DATE}" --pretty=format:" * %s") else # Fallback: get recent commits if date extraction fails CHANGES=$(git log --pretty=format:" * %s" -10) fi

If no changes, use generic message

If no changes, use generic message

if [ -z "$CHANGES" ]; then CHANGES=" * chore: bump version to ${TARGET_VERSION}" fi
undefined
if [ -z "$CHANGES" ]; then CHANGES=" * chore: bump version to ${TARGET_VERSION}" fi
undefined

Step 4: Get Author Information

步骤4：获取作者信息

bash
AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)

if [ -z "$AUTHOR_EMAIL" ]; then
    echo "Error: Git user.email not configured"
    echo "Please run: git config user.email 'your@email.com'"
    exit 1
fi

DATE_R=$(date -R)
bash
AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)

if [ -z "$AUTHOR_EMAIL" ]; then
    echo "Error: Git user.email not configured"
    echo "Please run: git config user.email 'your@email.com'"
    exit 1
fi

DATE_R=$(date -R)

Step 5: Get Package Name

步骤5：获取包名称

bash
PACKAGE_NAME=$(head -1 debian/changelog | sed -n 's/\([^ ]*\) .*/\1/p')
bash
PACKAGE_NAME=$(head -1 debian/changelog | sed -n 's/\([^ ]*\) .*/\1/p')

Step 6: Update debian/changelog

步骤6：更新debian/changelog

Create new entry at top of file:
text
${PACKAGE_NAME} (${TARGET_VERSION}) unstable; urgency=medium

${CHANGES}

 -- ${AUTHOR_NAME} <${AUTHOR_EMAIL}>  ${DATE_R}

<existing entries follow>
Example:
text
deepin-reader (6.5.47) unstable; urgency=medium

  * fix: correct .tx/config
  * chore: enhance service security
  * feat: add new feature

 -- Author Name <email@example.com>  Mon, 05 Jan 2026 15:29:58 +0800

deepin-reader (6.5.46) unstable; urgency=medium
...
Implementation:
bash
undefined
在文件顶部创建新条目：
text
${PACKAGE_NAME} (${TARGET_VERSION}) unstable; urgency=medium

${CHANGES}

 -- ${AUTHOR_NAME} <${AUTHOR_EMAIL}>  ${DATE_R}

<existing entries follow>
示例：
text
deepin-reader (6.5.47) unstable; urgency=medium

  * fix: correct .tx/config
  * chore: enhance service security
  * feat: add new feature

 -- Author Name <email@example.com>  Mon, 05 Jan 2026 15:29:58 +0800

deepin-reader (6.5.46) unstable; urgency=medium
...
实现代码：
bash
undefined

Read existing changelog

Read existing changelog

EXISTING=$(cat debian/changelog)
EXISTING=$(cat debian/changelog)

Create new entry (note: two spaces before each * and author line)

Create new entry (note: two spaces before each * and author line)

NEW_ENTRY="${PACKAGE_NAME} (${TARGET_VERSION}) unstable; urgency=medium
${CHANGES}
-- ${AUTHOR_NAME} <${AUTHOR_EMAIL}> ${DATE_R}
"
NEW_ENTRY="${PACKAGE_NAME} (${TARGET_VERSION}) unstable; urgency=medium
${CHANGES}
-- ${AUTHOR_NAME} <${AUTHOR_EMAIL}> ${DATE_R}
"

Write new content

Write new content

echo "${NEW_ENTRY}${EXISTING}" > debian/changelog

**Important formatting notes:**
- Each change line starts with **two spaces** + `*`: `  * fix: something`
- Author line starts with **two spaces** + `--`: ` -- Author <email>`
- Double newline between version entries
echo "${NEW_ENTRY}${EXISTING}" > debian/changelog

**重要格式说明：**
- 每条变更记录以**两个空格** + `*`开头：`  * fix: something`
- 作者行以**两个空格** + `--`开头：` -- Author <email>`
- 版本条目之间保留空行

Step 7: Update linglong.yaml (if exists)

步骤7：更新linglong.yaml（如果存在）

For each linglong.yaml file:
  • Update version field: 
    X.Y.Z.N
    → 
    X.Y.Z.N
    (update only first three parts)
  • Keep last number unchanged
Example: 
version: 6.5.46.1
→ 
version: 6.5.47.1
Implementation:
bash
if [ $HAS_LINGLONG -eq 1 ]; then
    TARGET_VERSION_NO_PATCH=$(echo $TARGET_VERSION | cut -d. -f1-3)
    find . -name "linglong.yaml" -type f -exec sed -i "s/version: [0-9]\+\.[0-9]\+\.[0-9]\+\.[0-9]\+/version: ${TARGET_VERSION_NO_PATCH}.1/g" {} \;
fi
对于每个linglong.yaml文件：
  • 更新版本字段：
    X.Y.Z.N
    → 
    X.Y.Z.N
    （仅更新前三个部分）
  • 保留最后一位数字不变
示例：
version: 6.5.46.1
→ 
version: 6.5.47.1
实现代码：
bash
if [ $HAS_LINGLONG -eq 1 ]; then
    TARGET_VERSION_NO_PATCH=$(echo $TARGET_VERSION | cut -d. -f1-3)
    find . -name "linglong.yaml" -type f -exec sed -i "s/version: [0-9]\+\.[0-9]\+\.[0-9]\+\.[0-9]\+/version: ${TARGET_VERSION_NO_PATCH}.1/g" {} \;
fi

Step 8: Commit Changes

步骤8：提交变更

bash
git add debian/changelog
if [ $HAS_LINGLONG -eq 1 ]; then
    git add $(find . -name "linglong.yaml" -type f)
fi

git commit -m "chore: update version to ${TARGET_VERSION}

- bump version to ${TARGET_VERSION}

Log : bump version to ${TARGET_VERSION}"
Commit message format:
  • Line 1: 
    chore: update version to <version>
    (lowercase)
  • Empty line
  • Bullet: 
    - bump version to <version>
    (lowercase)
  • Log prefix: 
    Log : bump version to <version>
    (note space after colon)
bash
git add debian/changelog
if [ $HAS_LINGLONG -eq 1 ]; then
    git add $(find . -name "linglong.yaml" -type f)
fi

git commit -m "chore: update version to ${TARGET_VERSION}

- bump version to ${TARGET_VERSION}

Log : bump version to ${TARGET_VERSION}"
提交消息格式：
  • 第一行：
    chore: update version to <version>
    （小写）
  • 空行
  • 项目符号：
    - bump version to <version>
    （小写）
  • 日志前缀：
    Log : bump version to <version>
    （注意冒号后有空格）

Common Mistakes

常见错误

MistakeWhy It's WrongFix
Creating git tagsThis skill only commits, does not tagUse separate command for git tag creation
Using git tags for change summaryGit tags may not exist for all releasesUse changelog date instead
Updating all parts of linglong versionOnly first three parts should changeUse 
X.Y.Z.1
pattern, not full version
Missing git user.emailAuthor information required for changelogConfigure 
git config user.email
Using "Release" in commitWrong commit message formatUse "chore: update version to X.Y.Z"
Forgetting to add linglong fileslinglong.yaml changes need to be committedUse 
find
to locate and add all linglong.yaml files
错误原因修复方案
创建Git标签本技能仅提交变更，不支持创建标签使用单独的命令创建Git标签
使用Git标签生成变更摘要并非所有版本都有对应的Git标签改用变更日志中的日期
更新linglong.yaml版本的所有四位数字仅需更新前三位数字使用
X.Y.Z.1
格式，而非完整版本号
Git user.email未配置变更日志需要作者信息执行
git config user.email
配置邮箱
提交消息中使用“Release”不符合提交消息格式规范使用“chore: update version to X.Y.Z”
忘记添加linglong.yaml文件linglong.yaml的变更需要提交使用
find
命令定位并添加所有linglong.yaml文件

Red Flags - STOP and Check

警示信号 - 立即停止并检查

  • Commit message doesn't follow exact format
  • Using git tags instead of changelog for change summary
  • linglong.yaml version changes all four parts
  • Missing git user.email configuration
  • debian/changelog doesn't exist
  • Trying to create git tags (not supported)
If any red flag appears, STOP and review the implementation section above.
  • 提交消息未遵循严格格式
  • 使用Git标签而非变更日志生成变更摘要
  • linglong.yaml版本的四位数字全部被修改
  • Git user.email未配置
  • debian/changelog不存在
  • 尝试创建Git标签（本技能不支持）
如果出现任何警示信号，请立即停止并查看上述实现步骤部分。