如何

开始贡献给Babylon.js


前言

Babylon.js的潜在贡献者可能来自许多不同的背景。对于您中的某些版本控制器,存储库,程序包管理器和任务运行器来说,它们是第二自然,您需要了解的就是Babylon.js核心团队为接受拉取请求而设置的要求。对于我们中的其他人,也许只是想探索3D世界,它们可能会成为一系列令人困惑的障碍。因此,此页面将包含许多人显然可以忽略的详细信息。对于其他人,这些细节可能是贡献与否之间的区别。

希望包括所有步骤,这些步骤将使所有具有适当编码技能的人员都可以做出贡献。

注意: 如果您希望为文档做出贡献,请使用this guide.

介绍

Babylon.js在Github上维护,Github是基于Web的托管服务,用于使用Git进行版本控制。该页面将介绍这些内容以及对Babylon.js进行更改或添加所需的一切,从工具安装到测试,并简要说明为什么有必要。这些步骤旨在与操作系统无关,允许用户在Windows,Mac和Linux上以相同的方式进行开发。

先决条件

  • 阅读 contribution guidelines.
  • 具有Typescript编码能力。Babylon.js用Typescript编写,然后用Javascript编译和分发。
  • 知道如何使用命令行解释器(CLI)。用于发出Git命令。

安装Git

对于Windows和Mac,一种快速的方法是从Git 主页中获取对于所有三个操作系统,都可以从Git Book获取。.

然后,您需要使用CLI将安装配置为您的详细信息。您可以使用计算机内置的CLI或Git的众多专业工具之一(Git客户端). 如果使用Visual Studio Code,则终端是内置的CLI,可以使用Ctrl +'打开。

在CLI中,使用用户名和电子邮件全局配置git:

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com

安装Firefox

为了运行Babylon.js测试,您将需要安装Firefox。

从Firefox主页下载它。

Github的叉子

如果您还没有开设一个使用您的电子邮件地址的Github帐户,并且仍在登录,请转到Babylon.js存储库并在顶部单击按钮。

Fork;

克隆到本地

现在,在Babylon.js存储库中,使用“克隆”或“下载”按钮查找您的存储库地址

Clone

如果您使用的CLI接受a,paste则使用地址右侧的复制图标。这将节省大量打字。

在CLI中输入

git clone _**your repository address**_

gitclone

克隆可能需要一些时间。

现在,您在Github上有一个本地存储库和一个远程存储库。

从将Babylon.js克隆到的文件夹中,您可以使用以下命令将目录更改为本地存储库

cd babylon.js

然后找到您的远程存储库的名称

git remote -v

remote address

您应该找到它的名称,origin因为它是克隆的本地版本的来源。本地版本称为,master因为它是Babylon.js的主版本。时间到了,这将允许您使用以下方法将本地存储库中的更改推送到Github存储库中

git push origin master

保持本地版本为最新

当您需要将所做的更改提取到Babylon.js中时,Babylon.js版本与您所做的更改之间的唯一区别就是。当然,其他人也在进行更改,因此您需要保持主版本(本地版本)与主版本保持最新。主要版本(通常称为上游版本)是本地存储库中可以链接到的另一个远程版本。

为此,您将主版本添加为远程版本,名称为上游,并确保您的CLI位于babylon.js目录中。

git remote add upstream https://github.com/BabylonJS/Babylon.js.git

运用

git remote -v

您可以检查所有遥控器是否处于活动状态。

Added Remote

现在,在将完全提交的主服务器推送到源服务器之前,您可以使用以下命令将上游(主)版本拉入您的主服务器

git pull upstream master

您可以随时从上游拉出,前提是您所做的任何更改都已提交。

编辑,测试和准则

在开始编辑或添加到Babylon.js之前,请确保您熟悉贡献准则。

请注意,其中一些是由软件自动检查提交的,包括

  • 如此处所述,在代码中添加注释;
  • 在dist / preview版本/new.md页面中添加有关更改的声明

使用Visual Studio Code编辑

Visual Studio Code是具有Git集成的直接IDE,可用于所有三个操作系统。尽管您可能已经拥有喜欢的或推荐的IDE,但是值得一试。

您可以从其网站安装VSCode:https://code.visualstudio.com/

一旦确定自己已满足准则并彻底测试了所有更改,就需要提交更改。

有关将VSCode与babylon.js结合使用的更多信息

新增档案

如果不确定应在何处引用文件,请在Babyon.js存储库中提出问题,或在论坛上提问。

承诺

可以在Visual Studio Code中使用左侧工具栏上的源代码控制图标或使用(Ctrl + Shift + G)来完成此操作。测试之后,除了您已添加或编辑的文件以外的其他文件将显示在VSCode的源代码控制部分中。例如,更改文件dist夹中的文件。这些不应该提交。一旦准备好推送到存储库,这些更改就应该被丢弃。只有您实际更改或添加的文件才应该在提交中。

Discard

使用Git Client时,还应检查您是否仅提交已添加或编辑的文件,而不提交任何测试版本中生成的文件。

使用CLI时,需要在提交之前添加已添加或编辑的所有文件。因此,仅添加您已更改的文件。必须使用当前目录中文件的完整路径。

例如在顶层目录

git add path to file/file1.ts path to file/file2.ts path to file/file3.ts
git commit path to file/file1.ts path to file/file2.ts path to file/file3.ts -m "Description of Changes"

Commit top Folder

并在包含file1.ts,file2.ts,file3.ts的目录中

git add file1.ts file2.ts file3.ts
git commit file1.ts file2.ts file3.ts -m "Description of Changes"

Commit in Folder

也可以在此页面上找到忽略测试构建期间更改的文件的另一种方法。

测试和依赖

为了进行测试,必须编译分发Javascript文件并设置服务器以进行测试。这需要Typescript编译器和Gulp构建工具。这些是使用npm(Node.js的程序包管理器)安装的。安装Node.js还将安装npm。

安装Node.js和NPM

可以从Node.js主页安装Node.js和npm 。

软件包管理器npm会定期更新,并且通常为了测试Babylon.js,您需要最新版本。在您的CLI中更新到最新版本

npm install -g npm@latest

在g安装全球NPM这样你就可以在任何文件夹中使用它

安装打字稿和Gulp

使用CLI安装这些

npm install -g typescript
npm install -g gulp@4.0.0

在撰写本文时,所需的Gulp版本为4.0.0。当前的“新功能”应该指示版本是否有任何更改。您也可以在Babylon.js存储库中查找package.json,Tools/Publisher其中将提供Gulp和Typescript的版本号。

建造

对于当前版本的Babylon.js,只需执行一次此操作,而在更高版本的Babylon.js中对npm或Gulp的更新可能需要您在本地计算机上更新npm和Gulp。完成后,您所做的任何更改都将被自动提取。在目录中安装npm应用程序需要花费相当长的时间,而Gulp的构建甚至需要更长的时间,因此,在Gulp运行时,这是获得选择咖啡或饮料的好时机。

任何未能通过构建的错误消息都应得到纠正。

在CLI中,确保您位于目录中,Babylon.js/Tools/Gulp然后输入

npm install
npm run build

在npm install一些在当前目录中的文件(这是不同的地方npm -g install,这将使得NPM任何文件夹中)

在npm run build建立你需要测试的一切。

不承诺

在构建过程中,dist文件夹会不断更新,其文件也会更改。这些修改的文件不应由Git提交,因此在拉取请求期间不会将它们拉出。要忽略这些文件,可以在CLI中运行以下命令:

git update-index --assume-unchanged "Playground/babylon.d.txt"
git update-index --assume-unchanged "dist/preview release/babylon.d.ts"
git update-index --assume-unchanged "dist/preview release/babylon.js"
git update-index --assume-unchanged "dist/preview release/babylon.max.js"
git update-index --assume-unchanged "dist/preview release/customConfigurations/minimalGLTFViewer/babylon.d.ts"
git update-index --assume-unchanged "dist/preview release/customConfigurations/minimalGLTFViewer/babylon.js"
git update-index --assume-unchanged "dist/preview release/customConfigurations/minimalGLTFViewer/babylon.max.js"
git update-index --assume-unchanged "dist/preview release/loaders/babylon.glTF2FileLoader.js"
git update-index --assume-unchanged "dist/preview release/loaders/babylon.glTF2FileLoader.min.js"
git update-index --assume-unchanged "dist/preview release/loaders/babylon.glTFFileLoader.js"
git update-index --assume-unchanged "dist/preview release/loaders/babylon.glTFFileLoader.min.js"
git update-index --assume-unchanged "dist/preview release/loaders/babylonjs.loaders.js"
git update-index --assume-unchanged "dist/preview release/loaders/babylonjs.loaders.min.js"
git update-index --assume-unchanged "dist/preview release/typedocValidationBaseline.json"
git update-index --assume-unchanged "dist/preview release/viewer/babylon.viewer.js"
git update-index --assume-unchanged "dist/preview release/viewer/babylon.viewer.max.js"

测试和调试

如果您使用的是VSCode,则可以Command Palette从View菜单中打开,也可以使用(Ctrl + Shift + P)打开,然后开始输入run内容,进入Tasks:run选项,选择Tasks:run并run在打开的框中输入内容。或者,按(Ctrl +')打开作为CLI的终端。

在任何CLI中,请确保您位于Tools/Gulp目录中并键入

npm run start

您可以使用(Ctrl + C)取消任务

使用VSCode时,您也可以通过Command Palette从View菜单中打开或使用(Ctrl + Shift + P)开始键入terminate并选择Tasks: Terminate Task选项来终止任务。

同样使用VSCode Debug,菜单上有一个选项卡。要将其与Babylon.js结合使用,您需要安装chrome调试器扩展,并从Debugger for Chrome中找到更多信息 。

运行任务后,下面的链接提供Babylon.js中的主要入口点:

  1. 沙箱: http://localhost:1338/sandbox/index-local.html
  2. 游乐场: http://localhost:1338/Playground/index-local.html
  3. 材料库: http://localhost:1338/materialsLibrary/index.html
  4. 后期处理库: http://localhost:1338/postProcessLibrary/index.html
  5. 程序纹理库: http://localhost:1338/proceduralTexturesLibrary/index.html
  6. 检查器: http://localhost:1338/inspector/index.html
  7. 本地开发人员: http://localhost:1338/localDev/index.html
  8. 构建验证: http://localhost:1338/tests/validation/index.html

所有这些都允许直接从typescript调试bjs的源代码。

debug

如果要测试完全编译的版本而不是独立文件,只需在不同的URL中附加?dist = true即可。

您还可以通过选择?dist = min对缩小版本进行测试。这将适用于所有引用的URL。

编辑代码

一旦启动测试任务(npm run start),Typescript或着色器文件中所有保存的更改将自动重建关联的Javascript文件。只需刷新浏览器以查看生效的更改并开始调试新代码。

提示:您可能需要先刷新代码,然后再添加新的断点。

本地开发人员与游乐场

测试您的代码是否有效的一种快速方法是打开本地游乐场 并编写调用您已创建的类的代码。

也可以通过index.js在/localDev/src/文件夹中创建文件,然后将游乐场代码复制并粘贴到该index.js文件中来实现。整个/localDev/src文件夹都会被忽略,它是您本地的测试文件夹。

您可以通过以下方式启动此代码 http://localhost:1338/localDev/index.html

从那里,您可以轻松地在游乐场代码或Typescipt文件中添加断点以进行调试。

在URL中添加?dist = true或?dist = min将有助于针对生成的文件进行测试。

由于仅使用一个测试文件很烦人,请随意为文件index.1.js,index.2.js ...等编号。在VSCode中,将文件复制粘贴到同一文件夹中会导致在文件夹中创建下一个可用插槽,例如,复制粘贴index.1.js将创建index.2.js。

要启动index。{number} .js,只需在url sample = {number}中附加,以便针对未缩小的已发布文件启动index.3.js,请使用:http://localhost:1338/localDev/index.html?dist=true&sample=3

这应该有助于在本地播放和调试。

验证变更

作为测试过程的一部分,强烈建议启动构建验证器:http://localhost:1338/tests/validation/index.html. 它将针对参考图像运行多个场景以检测任何视觉变化。

指导方针

提醒您阅读贡献准则。

拉取请求

拉取请求会自动验证。一张支票用于样式检查,您可以使用来快速检查gulp tsLint。如果不确定,可以使用完整版本验证所有内容:

npm run build

当您对所有测试均已通过验证感到满意时,将遵循准则并仅提交必要的文件,然后使用Git Client或使用CLI从本地主控器将其推送至原始github存储库

git push origin master

一旦成功,请访问您的Babylon.js存储库

如果所有提交都在上游Babylon.js:master之前,则可以使用下面显示的按钮发出拉取请求,然后按照步骤进行操作。

Success

如果您的某些提交在上游Babylon.js:master之后

fail

那么您将需要做一个

git pull upstream master

然后再次推送到您的存储库中。

检查成功

pull-request签发您的证件之后,需要对其进行检查,审查,批准和合并。

一些检查是自动执行的,可以在BabylonJS / Babylon.js主存储库中找到

从列表中找到您的拉取请求并打开它。

check 1

向下滚动到查看面板

check 1

如果有任何其他标记,则红叉指示故障区域。单击详细信息以获取更多信息。

向下滚动到“阶段1”部分

check 2

在上图中,您可以看到的拉取请求失败WhatsNewUpdate。可能是因为在dist / preview release / new.md中没有输入任何内容。DocumentationCheck由于已按照API注释格式中的说明输入了所有注释,因此它已通过。

对于任何失败,请重新编辑本地文件,然后提交并推送到存储库。更改将自动添加到您的请求请求中,并将重新检查。

这是活的

一旦合并您的请求请求,一旦将任何更改部署到Preview Release通常通常在一夜之间但有时会延迟几天的地方,它将立即生效。

Gulp任务

以下所有任务均可用:

  • gulp run 启动所有观察程序和Web服务器。
  • gulp webserver 仅启动Web服务器。
  • gulp watch 仅启动观察者。
  • gulp typescript-all 生成dist / preview版本文件夹中的所有分发文件
  • gulp typescript 生成BJS分发文件。
  • gulp typescript-libraries 生成dist / preview版本文件夹中的所有库文件(材质,过程纹理...)。
  • gulp loaders 生成dist / preview release文件夹中的所有加载程序文件。
  • gulp serializers 生成dist / preview版本文件夹中的所有序列化器文件。
  • gulp materialsLibrary 生成dist / preview版本文件夹中的所有资料文件。
  • gulp proceduralTexturesLibrary 生成dist / preview release文件夹中的所有过程纹理文件。
  • gulp postProcessesLibrary 生成dist / preview版本文件夹中的所有后处理文件。
  • gulp inspector 在dist / preview版本文件夹中生成检查器文件。

这些任务中的大多数应该通过依靠以下参数授权节点消耗比默认内存更多的内存来启动: --max-old-space-size=8192 摘要

摘要

应用安装

Node.js和Git

叉子和克隆

Fork and Clone

名称遥控器和拉

Remotes

全局安装

npm install -g typescript
npm install -g gulp@4.0.0

本地安装

Babylon.js/Tools/Gulp folder

npm install

本地版本

Babylon.js/Tools/Gulp folder

npm run build

网络服务器

Babylon.js/Tools/Gulp folder

npm run start

露天游乐场

重复

编辑

更改和保存包含注释的文件

测试

检查您的代码是否可以在本地游乐场使用

成功

更新/dist/preview release/what's new.md文件。
提交已添加或编辑的文件,但不是使用npm run start生成的文件

推送请求请求检查

Pull-Request