How to contribute to Babylon.js

Starting somewhere

As you surely know, Babylon.js is an open-source 3D engine, where the source code can be found on Github. The full list of all glorious contributors is also available on Github. If you also want to be part of this adventure and join this list, you're in the right place :) But what "contributing" means exactly ?

It means that each one of them have a sample of their code in the engine itself: a new feature, a bug fix, a new material, a new demo showing the full potential of a specific feature... If your code is good, useful and can be easily used, it's only a matter of time before your pull request will be accepted.

Where to contribute ?

You can contribute to several places:

Each one of these projects is a Github project, with its own rules you have to follow.

In this tutorial, we will learn how to configure a local project in order to be ready to contribute to the official engine. Several things will be aborded:

  • Create a Github account
  • How to fork and clone a project
  • How to setup your local copy to compile the engine with Visual Studio
  • The project code conventions
  • How to create a new pull request

I will use the awesome editor Visual Studio Code to edit and compile the project. VSCode can be found here. Let's start!

Git and Github

Babylon.js repository is located on Github. That means in order to contribute, you first have to create a free Github account. To do so, go to github.com, and fill the form with your account name, mail and password.

Once your account is created and validated, you can browse to the project homepage. On this page, you can find several information:

Let's explain the top right buttons on this screen:

  • The button "Watch" is used to toggle changes notifications on this project.
  • The button "Star" is used to check the popularity of a project. You can give a star to Babylon.js if you want to help it spread around the world!
  • The button "Fork" is used to create your own local copy of this project.

How to fork and clone the project

The first thing to do is to fork the project. Forking a project will create your own copy of the project. That means you can do whatever you want in your copy of Babylon.js without affecting the main repository :) Awesome right ? So let's fork Babylon.js.

After the nice animation is finished, you probably noticed the name of the project changed.

That means you're in your local copy! Congrats :) Let's go to the next step.

Clone the project, and using the git command line

Back to your computer! Before doing anything, you have to setup the softwares listed below. This tutorial won't describe how to install it, as it's veeeery easy to do it :)

Open cmder (or your new git bash), and type the following command:

> node -v
    v5.2.0
> npm -v
    v3.3.12

Now, go to the directory you want to have your project, and type the clone command. Replace Temechon by your Github account name:

> git clone https://github.com/Temechon/Babylon.js.git

The whole project will be retrieved on your computer. Keep in mind you are retrieving your fork of the project, not the official one.

Synchronize your fork with the official repo - Create an upstream link

An upstream link will help you retrieve all last changes from the official Babylon.js project. For this, we will follow this github tutorial:

> cd Babylon.js
> git remote -v
    origin  https://github.com/Temechon/Babylon.js.git (fetch)
    origin  https://github.com/Temechon/Babylon.js.git (push)
> git remote add upstream https://github.com/BabylonJS/Babylon.js.git
> git remote -v
    origin  https://github.com/Temechon/Babylon.js.git (fetch)
    origin  https://github.com/Temechon/Babylon.js.git (push)
    upstream        https://github.com/BabylonJS/Babylon.js.git (fetch)
    upstream        https://github.com/BabylonJS/Babylon.js.git (push)

Fetch the very last version

Ok! Now you're ready to retrieve all changes from the official repo. Each time you want to add a new feature, a bug fix, anything, you have to ensure you are working on the very last version. To do this, follow this Github tutorial:

> git fetch upstream
> git checkout master
> git merge upstream/master

And you're done! Now, let's setup the IDE and try to compile the project.

Install packages

In order to be able to compile, you have to install all needed packages. For this, we use the power of Node Package Manager. First, we install gulp globally (-g), and install all needed packages for this project:

> npm install -g gulp
> cd Tools/Gulp
> npm install

A lot of lines will be written... It may take a while, depending on your computer and the network speed. Go grab a coffee during this time :)

Setup Visual Studio Code

With VS Code, you can directly open the Babylon.js folder. Now we just have to configure the task runner of VSCode and we're done!

The task runner

In order to configure the task runner, press CTRL+SHIFT+P, and type config. you should have this line highlighted. Press enter:

The file tasks.json opens in edit mode. You can delete everything is paste this:

{
    "version": "0.1.0",
    "command": "gulp",
    "options": {
        "cwd": "${workspaceRoot}/Tools/Gulp"
    },
    "isShellCommand": true,
    "tasks": [
        {
            "taskName": "typescript",
            // Make this the default build command.
            "isBuildCommand": true
        },
        {
            "taskName": "default",
            "isBuildCommand": false
        },
        {
            "taskName": "watch-typescript",
            "isBuildCommand": false
        }
    ]
}

Save it. Now your VSCode is configured :) You can press CTRL+SHIFT+B in order to compile all TypeScript files.

The project code conventions

Now that you're ready to add your own code, please read and follow the project code conventions. If you don't follow these simple rules, your pull request may not be approved.

Commit and push

Once your new feature is developped and tested, you can commit and push to your repository. You can commit and push within VSCode, but you first have to tell him to remember your Github credentials. Otherwise, the 'push' command will be stucked and will run forever. Open your cmder (or the git bash), and use this:

> git config --global credential.helper wincred

You can learn more about it here.

Back to VSCode! By clicking on the Git icon (on the left), you can see how many changes have been done on the repo. You can click on the '+' icon to stage them, and specify a commit message for each one of them. CTRL+Enter to commit. When every file has its commit message, clic on the push button. This will send all your modifications to your fork. Now, we have to send it to the official repository \o/

Create a pull request

Everything happens on Github! Connect to your account, and go to your Babylon.js fork. Can you see this little greeny button over there?

You can click on it. Github will show all change you want to push to the official repo. Check this, and if you are sure, click on the button 'Create Pull Request'. Leave a small message, and confirm. The pull request will be automatically be checked by Travis, and manually reviewed by Babylon.js team. We are very reactive, and a pull request never stay uncommented for too long :)

Now what ?

Yay! You pushed a new feature in the official repository. You are now an official contributor! Congrats :)