为 MapLibre GL JS 做贡献

嗨，感谢您有意向为 MapLibre GL JS 做贡献；以下是我们的工作方式；提交问题或拉取请求时，请遵循这些约定；

不要违反 Mapbox 版权！

2020年12月，Mapbox 决定在专有许可证下发布 mapbox-gl-js 的未来版本；您不允许从在这个新许可证下贡献的 Mapbox 项目中移植代码；未经授权的移植是 MapLibre 项目面临的最大威胁；如果您对此问题不确定，请咨询！

贡献的最佳实践

MapLibre 欢迎社区的贡献！这个代码库庞大且复杂，遵循这些最佳实践将有助于维护团队审核您的贡献；总体而言，项目重视讨论和沟通，而不是过程和文档；然而，由于代码的规模和复杂性，以下是一些对贡献者有帮助的最佳实践；

在进行问题单或PR之前，最好先讨论您提议的更改；项目团队活跃在以下论坛：

  • 对于非正式聊天讨论，请访问项目的Slack频道；
  • 对于那些输出和结果不应该是短暂的讨论，请考虑在GitHub讨论中启动一个主题；这使得将来更容易找到和引用该讨论；

MapLibre软件严重依赖自动化测试，项目包含一套单元测试和集成测试；对于新功能和错误修复，贡献应更新或添加测试用例以防止回归；

新功能

对于新功能，通常最好先创建一个问题单；如果该功能需要对样式规范进行更改，应在样式规范的GitHub仓库中创建问题单；样式规范的更改很难后期修改，因此对规范的更改将受到特别严格的审查；

如果可能，有益于演示提议的新功能并评估其性能影响；您可以使用 npm install <maplibre源代码位置> 在npm环境中测试更改，或使用 npm run build-prod 构建一个.js包用于此目的；

对于需要更深入讨论的复杂功能提议，您应考虑在技术指导委员会会议中提出，与团队进行视频讨论；我们发现对于更重要的决策，有时更容易进行集中的面对面讨论；

技术指导委员会会议对任何想参与项目技术方向的人开放；这些会议提供了讨论和协作各种技术主题的机会；如果您有兴趣参与，我们欢迎您加入会议；

错误修复

如果您发现了一个严重的错误，或者您不打算自己修复的错误，请撰写一个描述问题的问题单；对于小型或直接的错误修复，请直接进行PR；

以下是针对错误修复PR的一些最佳实践：

  1. 首先编写一个失败的测试，展示当前软件无法按预期运行的情况；提交并推送分支；
  2. 创建一个草稿PR，记录不正确的行为；这将在项目的持续集成中显示您刚写的失败测试，证明问题的存在；
  3. 修复错误，并更新PR，在PR描述中添加任何其他需要说明的内容；
  4. 当您对代码更改满意时，不要忘记将PR标记为"可以审核"；

这不是一个严格的流程，而是一个指导方针，它将帮助建立信心，确保您的PR真正解决了问题；

准备开发环境

CodeSpaces

通过创建代码空间，您应该能够在后创建脚本完成运行后立即开始工作；这个脚本基本上安装了Linux部分中描述的所有内容；

macOS

安装Xcode命令行工具包

xcode-select --install

安装<.nvmrc>中指定的node.js版本

brew install node

克隆代码仓库

git clone git@github.com:maplibre/maplibre-gl-js.git

安装node_canvas的依赖项 (https://github.com/Automattic/node-canvas)

brew install pkg-config cairo pango libpng jpeg giflib librsvg

安装node模块依赖

cd maplibre-gl-js &&
npm install

Apple Silicon芯片

如果您使用的是较新的arm64架构机器，您可能会发现找不到适合您架构的canvas.node或webgl.node；在这种情况下，进入node_modules/canvas和node_modules/gl，然后运行：

npm install --build-from-source

如果您使用迁移助手从非M1机器迁移到M1机器，并且之前已安装brew，且在运行测试时遇到以下错误：

dlopen(/Users/[...]/common/temp/node_modules/.pnpm/canvas@2.11.0/node_modules/canvas/build/Release/canvas.node, 0x0001): symbol not found in flat namespace '_cairo_fill'

      at Object.<anonymous> (../../common/temp/node_modules/.pnpm/canvas@2.11.0/node_modules/canvas/lib/bindings.js:3:18)

尝试以下步骤：

  • 卸载然后重新安装brew
  • 运行arch -arm64 brew install pkg-config cairo pango libpng jpeg giflib librsvg
  • 删除node_modules文件夹并重新运行npm install

Linux (以及GitHub Codespaces)

安装git、GNU Make和libglew-dev

sudo apt-get update &&
sudo apt-get install build-essential git libglew-dev libxi-dev default-jre default-jdk xvfb

如果没有canvas和gl的预构建二进制文件，您还需要：

sudo apt-get install python-is-python3 pkg-config libpixman-1-dev libcairo2-dev libpango1.0-dev libgif-dev

安装nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

从.nvmrc安装Node.js

nvm install

克隆代码仓库

git clone git@github.com:maplibre/maplibre-gl-js.git

安装node模块依赖

cd maplibre-gl-js &&
npm install

在运行文档之前，您需要确保已安装Docker，并且您有权限无需sudo运行docker命令，具体请参考Docker文档；

Windows

考虑使用WSL并按照上面的Linux指南操作，或按照以下步骤进行：

安装git、node.js (<.nvmrc>中的版本)、npm和node-gyp；

克隆代码仓库

git clone git@github.com:maplibre/maplibre-gl-js.git

安装node模块依赖

cd maplibre-gl-js
npm install

安装headless-gl依赖 https://github.com/stackgl/headless-gl#windows

copy node_modules/headless-gl/deps/windows/dll/x64/*.dll c:\windows\system32

创建独立构建

独立构建允许您将此仓库的内容转换为可以包含在HTML页面上的maplibre-gl.js和maplibre-gl.css文件；

要创建独立构建，运行：

npm run build-prod
npm run build-css

这些命令完成后，您将在dist/maplibre-gl.js和dist/maplibre-gl.css位置获得独立构建文件；

测试更改和编写文档

参见docs/README.md

编写和运行测试

参见test/README.md

编写和运行基准测试

参见test/bench/README.md

更多指南

查看developer-guides目录获取有关发布流程和图块生命周期的指南；

代码约定

  • 我们使用错误事件来报告用户错误；
  • 我们使用TypeScript语言提供的最新特性，包括但不限于：
    • let/const
    • for...of循环（仅用于类数组迭代，即Bublé的dangerousForOf转换支持的内容）
    • 箭头函数
    • 类
    • 模板字符串
    • 计算和简写对象属性
    • 默认参数
    • 剩余参数
    • 解构
    • 模块

模块导出的约定是：

  • 不要导出"命名空间对象" - 模块应该导出类或函数，偶尔会有例外用于存根；
  • 如果模块导出的内容与文件名相同（忽略大小写），则应该是默认导出；
  • 其他任何内容都应该是命名导出；

为保持代码风格统一并避免常见错误，您可以使用以下脚本检查文件：

npm run lint
npm run lint-css

此外，如果您使用VSCode，"格式化文档"操作或"编辑器：保存时格式化"应该会默认强制执行此项目的js、ts和css格式规范；

版本控制约定

以下是推荐的设置方式：

  1. Fork此项目
  2. 克隆您的新fork，git clone git@github.com:GithubUser/maplibre-gl-js.git
  3. cd maplibre-gl-js
  4. 添加MapLibre仓库作为上游仓库：git remote add upstream git@github.com:maplibre/maplibre-gl-js.git
  5. 为您的贡献创建一个新分支git checkout -b your-branch
  6. 编写代码，准备好后从您的分支创建PR
  7. 如果您需要将fork的PR分支变基到main以解决冲突：git fetch upstream，git rebase upstream/main，然后强制推送到Github git push --force origin your-branch

更新日志约定

什么情况下需要添加更新日志条目？

  • 任何影响公共API、视觉外观或用户安全的更改必须有一个更新日志条目
  • 任何性能改进或错误修复应该有一个更新日志条目
  • 任何来自社区成员的贡献可以有一个更新日志条目，无论多小
  • 任何与文档相关的更改不应该有更新日志条目
  • 在同一版本中引入并修复的任何回归更改不应该有更新日志条目
  • 任何内部重构、技术债务减少、渲染测试、单元测试或基准测试相关的更改不应该有更新日志条目

如何添加您的更新日志？

  • 直接编辑<CHANGELOG.md>文件，在适当列表的顶部插入一个新条目
  • 任何更新日志条目都应该具有描述性和简洁；它应该能够向没有上下文的读者解释清楚变更内容

推荐阅读

学习WebGL

  • Greggman的WebGL文章
  • WebGL参考卡

GL性能

  • 调试和优化WebGL应用程序

其他

  • 绘制抗锯齿线条
  • 使用带符号距离场的绘制文本
  • 标签放置
  • 距离场