cyberark/parse-a-changelog

镜像概述

parse-a-changelog 是一个基于Ruby开发的工具镜像，用于验证变更日志文件（通常为CHANGELOG.md）是否符合keepachangelog.com定义的格式标准。该镜像将工具容器化，便于在各类环境（如本地开发、CI/CD流程）中快速部署和使用，无需手动配置Ruby运行环境及依赖。

核心功能与特性

• 格式验证：检查变更日志是否符合keepachangelog.com规范的结构要求，包括版本号格式、日期格式、变更类型分区（如Added/Changed/Deprecated等）等。
• 结构检查：验证文件是否包含必要元素（如版本标题、变更记录分区、链接引用等），识别缺失或错误的结构。
• 错误报告：提供详细的格式错误信息，包括错误位置和修复建议，便于快速定位问题。
• 轻量便捷：基于Ruby Slim镜像构建，体积小巧，启动快速，易于集成到自动化流程。
• 兼容性：支持标准Markdown格式的变更日志文件，兼容常见的变更日志编写习惯。

使用场景

• 本地开发：开发人员在提交变更日志前，通过容器快速验证文件格式，确保符合团队规范。
• CI/CD集成：作为代码提交或合并的前置检查步骤，在CI流程（如GitHub Actions、GitLab CI）中自动运行，阻止格式不合规的变更日志进入代码库。
• 开源项目维护：确保贡献者提交的变更日志符合社区通用规范，提升项目文档的一致性。
• 批量检查：对历史变更日志文件进行批量格式验证，统一项目文档风格。

使用方法

基本使用（docker run）

通过挂载本地变更日志文件到容器中，并指定文件路径进行验证：

bash
docker run --rm -v $(pwd):/workspace cyberark/parse-a-changelog parse-a-changelog /workspace/CHANGELOG.md

参数说明：

• --rm：容器运行结束后自动删除，避免残留容器。
• -v $(pwd):/workspace：将当前工作目录挂载到容器内的/workspace目录，使容器可访问本地的CHANGELOG.md文件。
• parse-a-changelog /workspace/CHANGELOG.md：容器内执行的命令，指定待验证的变更日志文件路径（容器内路径）。

配置参数

工具支持通过命令行参数调整验证行为，常见参数包括：

示例（严格模式验证）：

bash
docker run --rm -v $(pwd):/workspace cyberark/parse-a-changelog parse-a-changelog --strict /workspace/CHANGELOG.md

集成到CI/CD流程（示例：GitHub Actions）

在GitHub仓库中添加.github/workflows/validate-changelog.yml文件，实现提交时自动验证变更日志格式：

yaml
name: Validate Changelog
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Validate CHANGELOG.md format
        run: |
          docker run --rm -v $(pwd):/workspace cyberark/parse-a-changelog parse-a-changelog /workspace/CHANGELOG.md

注意事项

• 文件路径：确保挂载路径正确，容器内文件路径需与挂载目录对应（如本地./CHANGELOG.md需对应容器内/workspace/CHANGELOG.md）。
• 依赖文件：变更日志中引用的外部链接（如版本对比链接）需确保可访问，但工具主要验证格式而非链接有效性。
• 版本兼容性：工具版本需与keepachangelog.com规范版本匹配，建议使用最新版镜像以支持最新规范要求。