GraphHopper 开源贡献指南从 Issue 到 Pull Request 的完整实战流程【免费下载链接】graphhopperOpen source routing engine for OpenStreetMap. Use it as Java library or standalone web server.项目地址: https://gitcode.com/GitHub_Trending/gr/graphhopperGraphHopper 是一个基于 OpenStreetMap 的开源路由引擎既可以作为 Java 库嵌入应用也可以作为独立 Web 服务器运行用于计算两点之间的距离、时间、逐向导航指令及大量道路属性详见 README.md。本篇指南以官方贡献文档 CONTRIBUTING.md 为主线系统讲解如何正确提交 Issue、如何走完从 Fork 到 Pull Request 的完整提交流程、项目对测试与代码格式化的硬性要求以及翻译本地化的协作方式。读完本文你将掌握一套可以直接上手操作的 GraphHopper 贡献方法论并理解其背后的 Maven 构建与测试体系。项目定位与贡献者须知在动手贡献之前先了解你将要参与的项目结构。GraphHopper 采用 Maven 多模块工程组织见根目录 pom.xml当前仓库版本为 12.0-SNAPSHOT包含以下模块模块职责core核心路由引擎、图存储、路径算法与工具类reader-gtfsGTFS 公共交通数据读取与时变公交路由tools测量、调试可视化如 MiniGraphUI等工具map-matchingGPX 轨迹吸附到道路snap to roadweb-api/web-bundle/webHTTP API、Jersey 资源与服务端打包client-hcJava 客户端Routing / Matrix / Geocoding / Isochronenavigation供移动导航 SDK 消费的导航 Web 服务example官方示例程序Routing、Heading、Isochrone 等无论你贡献的是核心算法、Web API、地图匹配还是文档翻译下面的流程都适用。贡献的形式包括提交 Issue、修复 Bug、新增功能、改进文档、完善翻译。正确提交 Issue先把问题变成议题GraphHopper 官方对 Issue 的提交有明确边界目的是让维护者的时间花在真正的问题上仅在你确信它是缺失的功能missing feature或 Bug 时提交新 Issue。如果你只是有疑问、或者自己也不确定问题归属应当先到官方论坛的讨论区discuss.graphhopper.com 的 GraphHopper 板块发帖讨论而不是直接开 Issue。翻译相关的新增或修正不要走普通 Issue 流程请直接参考翻译文档 docs/core/translations.md其中描述了从翻译表格到代码合入的完整链路本文第 7 节会展开。项目用标签Label引导新人参与标记为good first issue的 Issue 面向首次贡献者通常难度可控、上下文完整标记为documentation的 Issue 属于文档改进类适合不想碰核心算法的贡献者。从仓库文档看README 的 Community 一节也强调先读贡献指南再动手见 README.md这与 CONTRIBUTING 的立场一致高质量的问题描述是高效率协作的前提。Pull Request 提交流程五步走官方给出的 PR 流程非常精炼完整步骤如下每一步都对应仓库的实际约束Fork 仓库并创建分支先 Fork GraphHopper 仓库到自己的账号再为你的新功能或 Bug 修复创建独立分支。不要直接在master上改独立分支便于维护者按功能审阅。运行测试项目只接受测试通过的 PR门槛命令是mvn clean test verify这条命令的每一段都有实际含义详见下一节测试规范与 Maven 构建体系它会在提交代码前把单元测试、集成测试和静态检查全部跑一遍。为你的改动至少添加一个测试只有**纯重构refactoring和文档改动documentation changes**可以不加新测试。此外有一个容易被忽视的硬性约定一个 PR 只对应一个 Issue。如果你同时有几个想改的点请拆成多个独立的 Pull Request 分别提交避免大杂烩式 PR 拖慢审阅。让测试通过在本地把新加的测试和既有测试全部跑绿。可以只跑单个模块或单个测试类来加快迭代但最终提交前必须通过完整验证。Push 到你的 Fork 并提交 Pull Request推送后你的 Fork 页面会出现提交 PR 的按钮在 PR 描述中清晰说明改了什么、解决了哪个 Issue、如何验证。从仓库的测试目录结构可以看出项目对测试的重视程度——仅core模块的测试就覆盖了routing路由算法、storage图存储、reader数据读取、util工具类等几乎全部子包例如 RoutingAlgorithmTest.java、GraphHopperTest.java 这类核心测试类。这也印证了官方那句话we love tests!——新代码带上测试既是贡献规范也是被合入的最快路径。测试规范与 Maven 构建体系要理解mvn clean test verify到底在做什么需要看根目录 pom.xml 的构建配置clean清理上一次构建产物确保从干净状态构建test执行单元测试。项目通过maven-surefire-plugin版本 3.5.4运行约定匹配*Test.java命名的测试类插件配置了-Duser.languageen参数保证测试在固定语言环境下运行、结果可复现verify执行集成测试并验证构建结果。maven-failsafe-plugin版本 3.5.4在integration-test和verify两个阶段运行约定匹配*IT.java命名的集成测试类例如reader-gtfs模块中的GraphHopperGtfsIT.java、FreeWalkIT.java以及web模块中的MapMatchingIT系列测试。此外构建链中还挂载了静态质量检查maven-checkstyle-plugin构建时执行代码风格检查配置指向 core/files/checkstyle.xml。从该配置文件看当前 checkstyle 规则相当克制仅限制单行长度上限max500说明项目的风格约束主要交给 IDE 与 EditorConfig见第 5 节checkstyle 只作为兜底防线forbiddenapis插件检查是否使用了 JDK 中已废弃deprecated的 API帮助代码保持与时俱进。同时需要注意pom.xml中maven.compiler.target与release均设置为25即当前仓库面向 Java 25 编译。因此本地构建/测试请使用 Java 25 及以上的 JDK否则无法通过编译阶段。代码格式化规范GraphHopper 对代码格式有明确约定贡献前请务必对齐否则 PR 会被格式检查或审阅者打回IntelliJ IDEA 用户直接使用 IntelliJ 的默认格式化配置即可Eclipse 用户官方提供了专门的格式化配置文件GraphHopper.Formatter.zip供导入其他 IDE仓库根目录提供了 .editorconfig被主流 IDE 原生支持打开项目即可自动套用。具体的格式化规则如下规则要求Java 缩进4 个空格行宽100 字符其余风格遵循通用 Java 编码标准保存行为禁用 auto-format on save避免产生大量无关的格式改动让 diff 聚焦于逻辑本身import 段目前不太强制但避免去改动它减少无谓冲突行尾Unix 换行符LF由 Git 的行尾处理保证这些规则与 .editorconfig 的实际内容完全一致该文件对*设置了indent_size 4、indent_style space、max_line_length 100、end_of_line lf、charset utf-8、insert_final_newline true并对*.json、*.yml/*.yaml单独设置了 2 空格缩进。也就是说除了 Java 代码你贡献的配置文件也要遵守统一的格式约定。License 协议与行为准则所有形式的贡献——包括 Pull Request、Bug 修复、文档改动和翻译——默认在 Apache License 2.0 条款下发布且贡献者需同意项目的 contributor covenant 行为准则contributor covenant code of conduct。Apache License 2.0 的选择是有意为之正如 README.md 所述该许可证便于开发者将 GraphHopper 嵌入自有产品甚至闭源产品同时项目方建议把改动回馈上游——这正是贡献流程存在的意义。作为贡献者提交代码即意味着你同意这一授权条款。翻译贡献从表格到代码的完整链路翻译是 GraphHopper 社区贡献最活跃的方向之一导航指令支持 45 种以上语言见 README.md 的 Features 列表。完整流程详见 docs/core/translations.md这里结合源码提炼关键步骤翻译约定先看懂规则语言名后面的两位字母是ISO 639-1 语言代码例如 de → 德语zh → 简体中文翻译条目中会出现%1$s之类的占位符由引擎在运行时填入具体参数如出口编号。占位符绝不能丢因为不同语言的语序完全不同。官方文档给出的例子英文 Enter roundabout and use exit %1$s德语必须写为 In den Kreisverkehr einfahren und Ausfahrt %1$s nehmen参数位置因语言而异。合入流程在官方翻译表格中为你的语言添加一列并定期回访更新条目本地跑通 GraphHopper参见 docs/core/quickstart-from-source.md新语言需要登记两处在TranslationMap.LOCALES中按字典序添加语言代码——该类位于 core/src/main/java/com/graphhopper/util/TranslationMap.java其中LOCALES列表以en_US为基准语言注释明确说明 use en_US as reference且en_US必须排在英语相关条目首位在脚本 core/files/update-translations.sh 的语言列表中同步添加从 Google 表格导出 TSV 数据并运行更新脚本cd graphhopper/core curl -L spreadsheet 的 TSV 导出地址 tmp.tsv ./files/update-translations.sh tmp.tsv rm tmp.tsvcore/files/update-translations.sh 内部会为每种语言生成src/main/resources/com/graphhopper/util/语言代码.txt翻译文件TranslationMap的doImport()运行时正是从这些 classpath 资源加载见 TranslationMap.java用git diff检查改动并用git status确认只有翻译文件这一处改动执行mvn clean test验证翻译没有遗漏参数占位符这正是上文约定中占位符不能丢的自动化兜底按 docs/core/quickstart-from-source.md 启动本地服务访问localhost:8989并在 URL 上追加localede以德语为例即可实时预览翻译效果最后按本文第 3 节的 PR 流程提交改动。需要特别说明只有逐向导航指令turn instructions是服务端处理的其余界面文案的翻译属于客户端GraphHopper Maps的职责走客户端项目的翻译流程两者不要混淆见 docs/core/translations.md 的 Client-side Translations 一节。新人快速上手建议从good first issue标签的 Issue 入手这些任务经过筛选适合第一次接触代码库的贡献者想从轻量贡献开始可以选documentation标签的文档类 Issue或直接改进翻译动手前先跑通本地构建与测试Java 25 mvn clean test verify一个能本地复现问题的环境是高效贡献的前提记住三个关键约定每个 PR 只解决一个 Issue、代码必须带测试重构/文档除外、遵循 4 空格缩进与 100 字符行宽的格式规范。按照上述流程提交的贡献既有测试背书、又符合格式与授权要求将最大程度降低维护者的审阅成本也让你的代码更快地合入这个被广泛使用的开源路由引擎。【免费下载链接】graphhopperOpen source routing engine for OpenStreetMap. Use it as Java library or standalone web server.项目地址: https://gitcode.com/GitHub_Trending/gr/graphhopper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考