企业官网建设流程全解析

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/graphhopper

GraphHopper 是一个基于 OpenStreetMap 的开源路由引擎，既可以作为 Java 库嵌入应用，也可以作为独立 Web 服务器运行，用于计算两点之间的距离、时间、逐向导航指令及大量道路属性（详见 README.md）。本篇指南以官方贡献文档 CONTRIBUTING.md 为主线，系统讲解如何正确提交 Issue、如何走完从 Fork 到 Pull Request 的完整提交流程、项目对测试与代码格式化的硬性要求，以及翻译本地化的协作方式。读完本文，你将掌握一套可以直接上手操作的 GraphHopper 贡献方法论，并理解其背后的 Maven 构建与测试体系。

项目定位与贡献者须知

在动手贡献之前，先了解你将要参与的项目结构。GraphHopper 采用 Maven 多模块工程组织（见根目录 pom.xml），当前仓库（版本为 12.0-SNAPSHOT）包含以下模块：

无论你贡献的是核心算法、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 流程非常精炼，完整步骤如下，每一步都对应仓库的实际约束：

1. Fork 仓库并创建分支：先 Fork GraphHopper 仓库到自己的账号，再为你的新功能或 Bug 修复创建独立分支。不要直接在master上改，独立分支便于维护者按功能审阅。

2. 运行测试：项目只接受测试通过的 PR，门槛命令是：

   mvn clean test verify

   这条命令的每一段都有实际含义（详见下一节"测试规范与 Maven 构建体系"），它会在提交代码前把单元测试、集成测试和静态检查全部跑一遍。

3. 为你的改动至少添加一个测试：只有**纯重构（refactoring）和文档改动（documentation changes）**可以不加新测试。此外有一个容易被忽视的硬性约定：一个 PR 只对应一个 Issue。如果你同时有几个想改的点，请拆成多个独立的 Pull Request 分别提交，避免"大杂烩"式 PR 拖慢审阅。

4. 让测试通过：在本地把新加的测试和既有测试全部跑绿。可以只跑单个模块或单个测试类来加快迭代，但最终提交前必须通过完整验证。

5. 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.language=en参数，保证测试在固定语言环境下运行、结果可复现；
• 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 规则相当克制，仅限制单行长度上限（max=500），说明项目的风格约束主要交给 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 原生支持，打开项目即可自动套用。

具体的格式化规则如下：

这些规则与 .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"，参数位置因语言而异。

合入流程

1. 在官方翻译表格中为你的语言添加一列，并定期回访更新条目；
2. 本地跑通 GraphHopper（参见 docs/core/quickstart-from-source.md）；
3. 新语言需要登记两处：
   • 在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 的语言列表中同步添加；
4. 从 Google 表格导出 TSV 数据并运行更新脚本：

   cd graphhopper/core curl -L '<spreadsheet 的 TSV 导出地址>' > tmp.tsv ./files/update-translations.sh tmp.tsv && rm tmp.tsv

   core/files/update-translations.sh 内部会为每种语言生成src/main/resources/com/graphhopper/util/<语言代码>.txt翻译文件（TranslationMap的doImport()运行时正是从这些 classpath 资源加载，见 TranslationMap.java）；

5. 用git diff检查改动，并用git status确认只有翻译文件这一处改动；
6. 执行mvn clean test验证翻译没有遗漏参数占位符（这正是上文约定中"占位符不能丢"的自动化兜底）；
7. 按 docs/core/quickstart-from-source.md 启动本地服务，访问localhost:8989并在 URL 上追加&locale=de（以德语为例）即可实时预览翻译效果；
8. 最后按本文第 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