GIS【免费下载链接】h3Hexagonal hierarchical geospatial indexing system项目地址https://gitcode.com/gh_mirrors/h3/h3点击查看免费下载本文基于 H3Hexagonal hierarchical geospatial indexing system仓库的 RELEASE.md 发布流程文档结合仓库中的 VERSION 文件、update-version脚本、CMake 配置与网站发布脚本系统讲解 H3 从代码合并到正式发版的全过程。读完本文你将掌握 H3 的版本号管理机制、make update-version的实际工作方式以及如何通过 PR、GitHub Release 与自动化流水线完成一次标准发布。一、发布流程总览H3 的发布流程分为三个核心阶段与 RELEASE.md 中记录的步骤一一对应准备发布 PR创建针对master分支的 Preparing for release X.Y.Z 合并请求更新 CHANGELOG 与 VERSION 文件经过评审后合并。创建 GitHub Release打vX.Y.Z标签并将 CHANGELOG 内容粘贴为发布说明。发布文档网站将最新文档发布到官网该步骤现已由 GitHub Actions 自动完成。三个步骤环环相扣版本号贯穿 CHANGELOG、VERSION 文件与 Git 标签三处任何一处不一致都会导致版本信息错位因此流程对版本号的一致性有非常明确的约束。二、第一步创建 Preparing for release PR2.1 更新 CHANGELOG.md发布的第一步是在master分支上创建一个标题为Preparing for release X.Y.Z的 PR其中 X.Y.Z 是目标版本号。在该 PR 中需要完成以下工作改写 CHANGELOG 标题将 CHANGELOG.md 顶部的[Unreleased]一节改为[X.Y.Z] YYYY-MM-DD格式其中 YYYY-MM-DD 为实际发布日期。当前仓库的 CHANGELOG 采用## [4.5.0] - 2026-05-21这样的格式这正是流程要求的产物。运行版本更新命令在build目录中执行make update-version并在提示时输入X.Y.Z。该命令会更新 VERSION 文件——注意流程明确要求不要手动修改 VERSION 文件必须通过该命令完成。核对变更完整性检查所有需要写入 CHANGELOG 的合并是否都已收录确保没有遗漏。评审并合并经过 reviewer 评审通过后合并该 PR。关于检查所有合并这一步可以从 scripts/update_version.sh 的实现中看到其背后的校验逻辑详见第三节。2.2 为什么必须通过make update-version更新版本号RELEASE.md 特别强调 VERSION 文件不要手动修改原因在于 VERSION 文件是版本信息的唯一权威来源。从 CMakeLists.txt 的源码可以看到file(READ VERSION H3_VERSION LIMIT_COUNT 1) # Clean any newlines string(REPLACE \n H3_VERSION ${H3_VERSION}) # Remove any trailing qualifier string(REGEX REPLACE -.*$ H3_VERSION ${H3_VERSION}) project( h3 LANGUAGES C VERSION ${H3_VERSION})CMake 在项目配置阶段直接读取 VERSION 文件首行作为H3_VERSION并将其作为project()的版本号。随后CMakeLists.txt 还会将H3_VERSION拆分为 MAJOR / MINOR / PATCH 三个部分用于后续的 SOVERSION 等导出设置string(REPLACE . ; H3_VERSION_LIST ${H3_VERSION}) list(GET H3_VERSION_LIST 0 H3_VERSION_MAJOR) list(GET H3_VERSION_LIST 1 H3_VERSION_MINOR) list(GET H3_VERSION_LIST 2 H3_VERSION_PATCH) set(H3_SOVERSION 1)此外版本号还会通过 h3.pc.in 模板Version: H3_VERSION注入 pkg-config 文件。因此VERSION 文件内容直接决定库的编译版本、CMake 导出版本与 pkg-config 报告版本手动修改极易引入格式错误如换行符、多余字符所以流程强制要求统一走脚本。三、make update-version底层实现剖析update-version是 CMake 中定义的 custom target见 CMakeLists.txt# Release publishing add_custom_target( update-version COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/scripts/update_version.sh WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})它会在源码根目录而非 build 目录执行 scripts/update_version.sh。该脚本的实际工作流程如下读取当前版本从 VERSION 文件读入当前版本号并构造当前 Git 标签v$CURRENT_VERSION。校验标签存在用git rev-parse检查当前版本对应的标签是否已存在若不存在则报错退出——这保证了版本号与 Git 历史严格对应。交互式输入新版本提示Next version:等待用户输入目标版本 X.Y.Z。展示变更审查信息脚本会用git diff $REVISION_RANGE -- CHANGELOG.md展示自上个标签以来 CHANGELOG 的改动用git log --oneline $REVISION_RANGE列出期间所有提交供发布者核对。确认后写入提示Are all changes in the changelog [y/N]?输入y或Y才将新版本号写入 VERSION 文件否则取消写入并提示先补充 CHANGELOG。该脚本为版本更新提供了三重保障标签可追溯当前版本必须有对应标签、变更可核对写版本前强制展示 diff 与提交日志、写入可确认人工确认 CHANGELOG 完整后才落盘。这正是 RELEASE.md 中检查所有需要进 changelog 的合并与不要手动改 VERSION两条要求的工程化实现。3.1 构建环境说明RELEASE.md 要求在build目录下执行make update-version前提是已经用 CMake 配置过构建目录生成对应的 Makefile。在支持 Makefile 生成器的环境中cmake 配置完成后即可使用该 target该 target 的工作目录被指定为源码根目录因此脚本能够正确读取 VERSION 文件并执行 Git 操作。Windows 等环境下 CMake 可能使用其他生成器届时对应 target 的执行方式以实际生成器为准。四、第二步创建 GitHub Release完成 PR 合并后进入第二阶段创建 Release在 GitHub 上创建标题为 Release X.Y.Z 的 Release。打标签为该 Release 创建vX.Y.Z格式的 Git 标签注意版本号前带有v前缀。粘贴发布说明将 CHANGELOG.md 中对应版本的内容复制到 Release 说明中。v前缀约定与update_version.sh中的标签构造逻辑一致CURRENT_TAGv$CURRENT_VERSION保证了版本文件、CHANGELOG、Git 标签三者格式统一。CHANGELOG 中每个版本的条目如## [4.5.0] - 2026-05-21即为 Release 说明的标准素材。从 CHANGELOG 的组织方式看H3 遵循 Semantic VersioningCHANGELOG.md 明确声明This project adheres to Semantic Versioning并约定公共 API 为 h3api.h.in 中声明的函数集合。这意味着 X.Y.Z 中的 Z补丁号代表不破坏 API 的修复Y次版本号代表向后兼容的新功能X主版本号代表不兼容的 API 变更——发布者在选择版本号时需要以此为准绳。五、第三步发布文档网站RELEASE.md 指出网站发布现在应该由 GitHub Actions 自动完成。仓库中的 scripts/publish_website.sh 记录了该自动化背后的手动逻辑脚本注释说明其现在的作用是构建当前版本文档并推送生产环境假设 gh-pages 远程指向上游仓库git checkout gh-pages git pull git checkout master pushd website ./scripts/build-to-gh-pages.sh git push git checkout master popd其核心思路是切换到gh-pages分支拉取最新内容切回master后进入 website 目录构建文档站点Docusaurus 站点配置文件为 website/docusaurus.config.js再推送回gh-pages分支。在实际发布流程中这一系列操作已被 GitHub Actions 流水线替代发布者无需手动执行。值得注意的是website 目录下同时维护着docs当前版本文档与versioned_docs如 version-3.x 的历史版本文档因此每次发版后网站更新会同时反映新版本 API 文档与历史版本归档。六、发布检查清单综合上述流程一次完整发布需要核对以下关键点阶段动作一致性要求PR 准备CHANGELOG 的[Unreleased]改为[X.Y.Z] YYYY-MM-DD版本号与目标一致PR 准备make update-version更新 VERSION 文件不要手动改 VERSION脚本会校验当前标签存在、展示变更、人工确认PR 准备核对所有合并均写入 CHANGELOG遗漏会导致版本信息不完整PR 评审获取 reviews 并合并 PR经过评审流程GitHub Release创建vX.Y.Z标签v前缀与脚本约定一致GitHub Release复制 CHANGELOG 对应版本内容到发布说明与 CHANGELOG 一致网站发布由 GitHub Actions 自动完成无需手动干预七、相关仓库文件索引RELEASE.md发布流程权威文档CHANGELOG.md变更记录遵循 Semantic Versioning公共 API 以 h3api.h.in 为准VERSION当前版本号仓库当前为 4.5.0由update-version维护scripts/update_version.shmake update-version实际执行的版本更新脚本CMakeLists.txt读取 VERSION 文件并注入project()版本号CMakeLists.txt 拆分 MAJOR/MINOR/PATCHCMakeLists.txt 定义update-versiontargeth3.pc.inpkg-config 模板其中H3_VERSION引用版本号scripts/publish_website.sh网站发布脚本现由 GitHub Actions 自动执行赞分享GIS【免费下载链接】h3Hexagonal hierarchical geospatial indexing system项目地址https://gitcode.com/gh_mirrors/h3/h3点击查看免费下载相关推荐Mackup 版本发布全流程指南从 Changelog 更新到 PyPI 发布Mackup 版本发布全流程指南从 Changelog 更新到 PyPI 发布 Mackup一个用于备份并同步应用配置文件的跨平台工具的维护者通过 doc开发工具CLI配置管理Wasmer 发布流程全指南从版本号更新、CHANGELOG 生成到 crates.io 发布Wasmer 发布流程全指南从版本号更新、CHANGELOG 生成到 crates.io 发布 导读 本文基于 docs/dev/release.md htt语言运行时JIT编译免费替代 Armoury Crate华硕笔记本 G-Helper 单文件轻量控制工具 5 分钟上手与调校指南免费替代 Armoury Crate华硕笔记本 G Helper 单文件轻量控制工具 5 分钟上手与调校指南 重装系统后任务管理器里 Armoury Cra桌面应用系统编程上一篇Camelidae-8x7B代码生成实战Python、JavaScript与Java编程助手下一篇Roc 语言嵌套标签模式匹配从 Err(Exit(code)) 到 dev_object 快照测试的完整解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考