nargo-changes

🎯 简介

nargo-changes 是 Nargo 框架的核心组件，负责版本变更管理，用于跟踪和管理代码变更，生成标准化的 changelog。它通过结构化的变更集管理，确保项目的版本历史清晰可追溯，为团队协作和版本发布提供有力支持。

✨ 核心特性

变更类型管理

• 多种变更类型: 支持 breaking、feature、fix、docs、refactor、perf、test、build、chore 等多种变更类型
• 类型验证: 自动验证变更类型的有效性
• 类型优先级: 基于变更类型的优先级排序，确保重要变更优先显示

变更集管理

• 结构化存储: 将变更集存储为 JSON 文件，便于版本控制和审查
• 变更集验证: 自动验证变更集的完整性和有效性
• 变更集合并: 支持合并多个变更集，便于批量处理
• 变更集历史: 维护变更集的完整历史，便于追溯

Changelog 生成

• 标准化格式: 自动生成符合规范的 changelog
• 版本分组: 按版本号分组变更，清晰展示每个版本的变更内容
• 变更分类: 按变更类型分类展示，便于快速了解变更性质
• 自定义模板: 支持自定义 changelog 模板，满足不同项目的需求

包影响跟踪

• 多包支持: 跟踪变更影响的包，便于版本管理
• 依赖分析: 分析变更对依赖包的影响
• 版本管理: 基于变更影响自动建议版本号变更

变更分析和统计

• 变更统计: 提供变更统计数据，包括变更类型分布、包影响分析等
• 趋势分析: 分析变更趋势，包括变更率、趋势方向等
• 报告生成: 生成包含统计数据和趋势分析的综合变更报告
• 可视化支持: 提供数据可视化支持，便于直观理解变更情况

🚀 使用方法

命令行使用

# 创建变更集
nargo changes add --type feature --summary "Add new feature" --description "Add a new feature to the framework" --packages nargo-core,nargo-compiler

# 列出所有变更集
nargo changes list

# 生成 changelog
nargo changes generate --version 1.0.0 --date 2024-01-01

# 清理变更集
nargo changes clear

# 获取变更统计
nargo changes stats

# 分析变更趋势
nargo changes trend --period 30d

# 生成变更报告
nargo changes report --period 30d

API 使用

基本使用

use nargo_changes::{ChangeSet, ChangeSetManager, ChangeType};
use std::path::Path;

// 创建变更集管理器
let manager = ChangeSetManager::new(Path::new(".changes"));

// 创建变更集
let change_set = ChangeSet {
    id: "123456".to_string(),
    r#type: ChangeType::Feature,
    summary: "Add new feature".to_string(),
    description: Some("Add a new feature to the framework".to_string()),
    author: Some("John Doe".to_string()),
    packages: vec!["nargo-core".to_string(), "nargo-compiler".to_string()],
    prerelease: false,
};

// 保存变更集
manager.create_change_set(&change_set).unwrap();

// 生成 changelog
let changelog = manager.generate_changelog("1.0.0", "2024-01-01").unwrap();
println!("{}", changelog);

// 清理变更集
manager.clear_change_sets().unwrap();

变更分析和统计

use nargo_changes::{ChangeSet, ChangeSetManager, ChangeType};
use std::path::Path;

// 创建变更集管理器
let manager = ChangeSetManager::new(Path::new(".changes"));

// 创建多个变更集
let change_sets = vec![
    ChangeSet {
        id: "1".to_string(),
        r#type: ChangeType::Feature,
        summary: "Add new feature".to_string(),
        description: None,
        author: None,
        packages: vec!["nargo-core".to_string()],
        prerelease: false,
    },
    ChangeSet {
        id: "2".to_string(),
        r#type: ChangeType::Fix,
        summary: "Fix bug".to_string(),
        description: None,
        author: None,
        packages: vec!["nargo-compiler".to_string()],
        prerelease: false,
    },
];

// 保存变更集
for change_set in &change_sets {
    manager.create_change_set(change_set).unwrap();
}

// 获取变更统计
let stats = manager.get_change_stats().unwrap();
println!("{}", stats.generate_summary());

// 分析变更趋势
let trend = manager.analyze_change_trend("30 days").unwrap();
println!("{}", trend.generate_summary());

// 生成变更报告
let report = manager.generate_change_report("30 days").unwrap();
println!("{}", report);

🔧 配置选项

nargo-changes 支持通过 nargo.config.toml 文件进行配置：

[tool.nargo.changes]
# 变更集存储目录
changes_dir = ".changes"

# Changelog 配置
[tool.nargo.changes.changelog]
# 输出文件路径
output_path = "CHANGELOG.md"
# 模板路径
template_path = "changelog-template.md"
# 是否包含作者信息
include_authors = true
# 是否包含包信息
include_packages = true

# 变更分析配置
[tool.nargo.changes.analysis]
# 趋势分析周期
trend_period = "30d"
# 是否生成可视化报告
generate_visualization = true
# 可视化输出格式
visualization_format = "svg"

# 变更类型配置
[tool.nargo.changes.types]
# 自定义变更类型
custom_types = [
  { name = "security", description = "Security improvements", priority = 2 }
]
# 变更类型排序
type_order = ["breaking", "feature", "fix", "security", "perf", "refactor", "docs", "test", "build", "chore"]

📊 与其他变更管理工具对比

🎯 应用场景

版本发布管理

在版本发布过程中，nargo-changes 可以帮助团队跟踪和管理变更，生成标准化的 changelog，确保版本发布的透明度和可追溯性。

团队协作

在团队协作中，nargo-changes 可以帮助团队成员了解项目的变更历史，便于协作和代码审查。

开源项目管理

在开源项目中，nargo-changes 可以帮助维护者跟踪和管理贡献，生成标准化的 changelog，提高项目的专业性和可维护性。

企业项目管理

在企业项目中，nargo-changes 可以帮助企业跟踪和管理代码变更，生成标准化的 changelog，满足合规要求和审计需求。

🔧 核心 API

ChangeSet

变更集的核心数据结构，包含变更的详细信息：

• id: 变更集的唯一标识符
• type: 变更类型（breaking、feature、fix 等）
• summary: 变更的简短描述
• description: 变更的详细描述（可选）
• author: 变更的作者（可选）
• packages: 变更影响的包列表
• prerelease: 是否为预发布变更

ChangeSetManager

变更集管理器，负责变更集的创建、读取、生成等操作：

• create_change_set: 创建新的变更集
• read_change_sets: 读取所有变更集
• generate_changelog: 生成 changelog
• clear_change_sets: 清理变更集
• get_change_stats: 获取变更统计数据
• analyze_change_trend: 分析变更趋势
• generate_change_report: 生成变更报告

ChangeStats

变更统计数据，包含变更的统计信息：

• total_changes: 总变更数
• type_distribution: 变更类型分布
• package_impact: 包影响分析
• author_contribution: 作者贡献分析
• generate_summary: 生成统计摘要

ChangeTrend

变更趋势分析，包含变更的趋势信息：

• change_rate: 变更率
• trend_direction: 趋势方向
• peak_periods: 变更高峰期
• generate_summary: 生成趋势摘要

🏗️ 模块结构

change_set

变更集的核心实现，包含变更集的定义和操作：

• ChangeSet: 变更集的数据结构
• ChangeType: 变更类型的定义
• ChangeSetValidation: 变更集的验证逻辑

manager

变更集管理器的实现，负责变更集的管理和操作：

• ChangeSetManager: 变更集管理器
• ChangeSetStorage: 变更集的存储逻辑
• ChangelogGenerator: Changelog 的生成逻辑

analysis

变更分析的实现，包含变更统计和趋势分析：

• ChangeStats: 变更统计数据
• ChangeTrend: 变更趋势分析
• ReportGenerator: 变更报告生成

🔗 相关项目

• nargo-types: 基础类型定义
• nargo-tools: 命令行工具集成
• nargo-release: 版本发布工具，与变更管理配合使用
• nargo-registry: 包注册表客户端

📚 文档

• 官方文档 - 详细的使用文档
• API 参考 - 完整的 API 参考
• 最佳实践 - 变更管理最佳实践指南

🤝 贡献

我们欢迎所有形式的贡献！请查看 贡献指南 了解如何开始。

⚖️ License

MIT.

📞 联系我们

如有任何问题或建议，欢迎通过以下方式联系我们：

• Email: team@nargo.dev
• GitHub: nargo-js/nargo