跳到主要内容

Debian Changelog 管理指南

1. 概述​

Debian changelog是Debian包维护中的重要组成部分，用于记录软件包的版本变更历史。本教程介绍如何使用dch工具正确创建和管理changelog文件。

2. 环境准备​

2.1 安装必要工具​

# 安装devscripts包（包含dch工具）
sudo apt update && sudo apt install devscripts

2.2 配置环境变量​

# 设置维护者信息
export DEBFULLNAME="Debian Package Maintainer"
export DEBEMAIL="maintainer@example.com"

3. 使用dch创建Changelog​

3.1 基本用法​

# 进入项目目录
cd /path/to/project

# 创建新的changelog条目
dch --newversion "1.0.0-1" \
    --distribution "bookworm" \
    --urgency "medium" \
    "Update package version"

3.2 参数说明​

参数说明示例
--newversion新版本号"1.0.0-1"
--distributionDebian发行版代号"bookworm"
--urgency更新紧急程度"low"/"medium"/"high"
--package包名（可选）"package-name"
--force-bad-version允许非常规版本号-

4. Changelog格式规范​

4.1 标准格式​

package-name (version) distribution; urgency=level

  * Change description (one or more lines)
  * Another change description

 -- Maintainer Name <maintainer@example.com>  Day, DD Mon YYYY HH:MM:SS +ZONE

4.2 示例条目​

mypackage (2.0.1-1) bookworm; urgency=medium

  * Update core components
  * Fix security vulnerabilities
  * Improve performance

 -- Debian Package Maintainer <maintainer@example.com>  Sat, 31 May 2025 10:00:00 +0800

5. 高级用法​

5.1 直接编辑方式​

如果dch工具限制较多，可以直接编辑changelog文件：

# 使用文本编辑器
nano debian/changelog

# 或使用echo写入
cat > debian/changelog <<EOF
mypackage (2.0.1-1) bookworm; urgency=medium

  * Update package version

 -- Debian Package Maintainer <maintainer@example.com>  Sat, 31 May 2025 10:00:00 +0800
EOF

5.2 批量更新​

# 添加多个变更记录
dch -a "First change"
dch -a "Second change"
dch -a "Third change"

6. 常见问题解决​

6.1 未来日期警告​

问题：dch拒绝使用未来日期 解决：使用--force-bad-version参数或手动编辑文件

6.2 格式错误​

问题：changelog格式验证失败 解决：

  1. 检查空格和缩进
  2. 确保日期格式正确
  3. 验证邮箱格式

6.3 版本号问题​

问题：版本号格式不正确 解决：确保遵循Debian版本号规范（主版本号-修订号）

7. 最佳实践​

  1. 版本号管理：

    • 遵循语义化版本规范
    • 保持版本号递增
    • 适当使用修订号

  2. 变更记录：

    • 使用清晰简洁的描述
    • 每条记录一个具体变更
    • 包含重要的技术细节

  3. 维护建议：

    • 定期更新changelog
    • 保持格式一致性
    • 备份重要的changelog文件

8. 注意事项​

  1. 确保时区设置正确
  2. 保持一致的维护者信息
  3. 遵循Debian政策规范
  4. 定期验证changelog格式
  5. 在提交前进行格式检查