如何与我们共建 Galacean 开源互动引擎

Galacean 在 GitHub 全流程开源管理

Galacean Engine 是 MIT 协议的开源互动引擎，我们 拒绝 KPI 开源、按揭开源、一次性开源，围绕着 GitHub 构建全流程开源管理模式。或许你已经看过了我们的仓库，我们的代码。但包括 Galacean 的规划，里程碑，优先级，架构设计在内的信息，你知道如何在我们的 GitHub 项目下获取吗？ 或许当你了解了这些信息，会对 Galacean 有更多期待，更重要的是对未来业务上可以使用的引擎技术有所预期。

子项目（Projects）

在 Galacean 项目下，可以看到这里有一个 Projects 规划。在这里你可以看到 Galacean 所有子项目的对应规划，负责人，和对应仓库： 以物理为例，点开后会看到卡片式的列表，包括 To do，In progress，Done。这三列当中的每一项其实都对应着一条 Issue 和 pr。仔细看会发现每一条左下角都有标记了 0.6, 0.7 这样的数值，这对应着我们的不同里程碑。这样一来，通过列表你就能对子项目的里程碑规划有一个全面的认识，并且了解未来 Galacean 会发布什么样的功能。

里程碑规划（Milestones）

上面的子项目往往对应着每一个子功能的开发进度，那么一个里程碑我们会做什么样的功能呢？在上述列表中我们可以看到 0.6 里程碑的标号，但对 0.6 里程碑还缺少一个整体的认识，所以我们其实还需要一个 横向整合 的工具，将上述子项目的 纵向规划 整合起来。 ​

在每一个里程碑初期，我们都会进行里程碑规划，首先我们会看一下Issue： 这里这里有一个 Milestones 的链接，进入之后你会看到我们当前的几个里程碑，例如： 此时你可以一目了然地知道当前 Engine 这个仓库对 0.6 里程碑的实现进度。进入后就可以看到非常具体的里程碑研发列表： 这里就需要特别指出，Galacean 使用 三标签管理机制，分为：功能领域（对应Project）+分类（指向功能的什么问题）+优先级，图中可以看到的都是当前里程碑中最为优先的特性，会首先实现出来，后续的低优先级特性我们会放到有时间的时候做，或者下个里程碑再来完成。通过这一 GitHub 集成的工具，很容易就进入到各个 Issue 和 PR 页面查看并参与讨论。 ​

知识库（Wiki）

通过子项目和里程碑，你可以很容易从横向，纵向两个方向对 Galacean 未来的发展和当前的状态有一个了解。除此之外，我们将开发过程中的架构总结以及 Checklist 放到了知识库当中，开发者可以通过 Wiki 了解我们设计的思想和技术细节。 图中可以看到的就是我们当前 0.6 里程碑的开发进度，包括了引擎和编辑器侧的全部规划和进度，也包括了其余二方库的开发进度。更重要是你可以看到我们这个里程碑的全部研发周期，在 11 月 10 日前后，我们就会发布全新版本的 Galacean，届时用户还可以通过我们的微信公众号了解这个里程碑的功能简报。 ​

除此之外，你还能看到右侧会有架构设计的细节，以这一里程碑推出的 InputManager 为例： 你可以通过这些介绍，理解引擎底层技术的设计与实现，如果你想要实现一个自己的引擎，也可以从中汲取灵感。 ​

分支管理（Branch）

通过上述流程，想必你对 Galacean 各个子项目的规划，里程碑规划，当前开发进度，引擎设计等各个方面都有所了解，或许你已经心痒新的功能，等不及在自己的项目中用起来。想要获得目前正在开发过程中的代码，应该很自然就想到了分支。 Galacean 的分支管理主要是三个部分：

1. 过去：0.XXX 分支：表示已经过去里程碑发布的代码，基本不会做修改。
2. 现在：main 分支表示最新发布的引擎的代码，也是我们当前业务中正在使用的代码。例如上个月刚发布 Galacean 0.5，我们目前正在开发里程碑 0.6 的功能。修复的 bug 会合并到 main 分支上，增强上个里程碑代码的健壮性。
3. 将来：dev/XXX 分支：表示当前正在开发的里程碑代码，所以，最新最新的特性，你可以在这里看到！

快速入手

尽管上述介绍的工具可以让你非常综合地了解 Galacean 当下的发展状态以及未来的目标，但想要在自己的业务中快速落地似乎还存在距离。为此，Galacean 提供了文档，范例（PlayGround），脚手架等辅助，并且这些都可以在GitHub 仓库中找到！ ​

项目脚手架（create-galacean-app）

你可以使用项目脚手架来生成已经配置好的 Galacean 开发项目，并且选择包括 React，Vue 等前端开发框架，方便你快速开发出前端所需要的组件，并且将开发成果用于自己的业务当中。 ​

功能脚手架（Playground）

项目脚手架只提供了配置好的环境，但是你如果想要快速尝试某个功能，并在此基础上迭代开发自己的项目，那就最好参考我们提供的 Playground，一种方式是直接看我们官网上的演示和代码，另外一方面你可以进入到官网的项目中，直接 npm run playground 就可以运行这些代码片段，并且他们的基础上迭代开发自己的项目。 ​

例如，你可以基于 FlappyBird 这个简单的游戏，迭代出自己的 2D 游戏。我们非常欢迎我们的用户提供自己的脚手架项目，例如你可以将项目中的保密信息删除，只保留一个可运行的基本框架，然后提交 PR 到 Playground目录，一旦 CR 通过，那么行业中的其他开发者就可以从我们的官网看到你的成果。 ​

总结

通过上述介绍，你或许对 Galacean 有了更多的了解。其中有三个概念最为重要：

1. 三标签管理：功能+特性+优先级。通过三标签我们在规划里程碑功能时很容易筛选出高优先级的需求。
2. 分支管理：如果你想要尝鲜，欢迎了解我们当前正在开发的 dev/XX 分支，如果希望业务稳定，欢迎使用main 分支。
3. 脚手架工程：方便用户快速配置环境，快速开始项目迭代。

Galacean 致力围绕开源构建自己的工作方式，除了上述偏向于静态的方式，也欢迎关注我们的微信公众号，钉钉开发者群，你的相关问题，我们会第一时间进行回答。我们也欢迎更多的分享和交流，激发 Web 3D 更加开阔的想象力。

具体实战

提出问题

发现了一个 bug？讨论新需求？或者答疑沟通？Issue 区域欢迎你！ 为了高效共建开源社区，在 issue 区我们约定：

1. 提问前先搜索已有帖子
2. 问题描述清晰
3. 如果是 bug，建议使用 jsFiddle, jsBin 等平台提供 demo，或者详细复现流程。

贡献代码

你发现了引擎的一个 bug 跃跃欲试？或者等不及想在某个 feature 上大展身手？那么接下来的介绍将带你从 Galacean 使用者一步步成为一个开发者。

开发环境（Setting up）

环境要求： 安装 12 版本及更新的 Node.js (nodejs.org)。可以通过 node -v确认已安装的版本。 FORK： 找到目标子项目，将其 Fork 到自己的 github 上 本地运行： clone 已经 fork 到自己仓库的 repository 到本地，运行npm run bootstrap 安装依赖 ​

贡献代码（Making a change）

确认分支 ：应该 checkout 哪个分支呢？根据上述分支管理，如果是修复 bug，使用 main 分支；如果是添加feature，使用最新 dev/XX 分支。 新建分支 ：在正确的分支之下git checkout -b <your branch name> 贡献代码： 在自己的分支下为所欲为之前，请查看开发规范 ​

测试一下（Test your change）

别急！在正式提交之前先测试一下吧！你可以选择 playground： 使用功能脚手架（Playground） 单测： 写单测，运行npm run test 执行测试用例验证结果 ​

提交PR（Submitting a Pull Request）

测试通过，现在万事俱备现在就差提交了！且慢，在 commit 之前还有一件事你需要知道。为了让所有参与者都能快速知晓代码内容，对于 commit message 我们有共同约定。比方说，如果你在 compiler 中增加了一个新功能，commit message 就可以写作：

feat(compiler): add 'comments' option

提交PR： 在 commit 并且将其 push 到自己仓库的 fork 之后，打开对应的 Galacean 项目会有这样的提示 点击进入，保证自己在正确的 branch 上，依次填写正文内容后，就可以提交 PR 了！

PR审阅 (Reviewing a Pull Request)

你收到了邮件，说某某 commented on this pull request。仔细思索之后，你采纳了这个意见并且对自己的代码进行了修改。接下来，你需要重新测试并提交代码。

git commit --all --fixup HEAD
git push

或者你收到的意见中包括 修改 commit message，那么你可以：

git checkout my-fix-branch 
git commit --amend 
git push --force-with-lease /

_*如果你需要修改更早提交的 commit message，了解一下 __git rebase_ ​

经历了几轮讨论之后，你的 PR 被合并 了！这个时候可以安全的删除自己的分支，和上游仓库保持一致。

git push origin --delete my-fix-branch
git checkout master -f
git branch -D my-fix-branch
git pull --ff upstream master

就是这样，非常感谢你的贡献！ ​

总结

通过上述步骤，你已经了解了 Galacean 开发者工作流程。其中有几个点需要强调：

1. FORK：我们强烈推荐通过 fork 到本地仓库的方式提 PR
2. 测试：所有引擎代码都需要经过测试
3. 规范：你可能发现针对 commit message 和代码格式，我们都有统一的规范要求。如果有疑问可以查阅我们引擎仓库中的代码规范 ​