Using Github To Contribute

From WebGL Public Wiki
Jump to: navigation, search

The Draft WebGL Specification, WebGL extension registry, and the WebGL Conformance Test Suite are hosted on github at

If you'd like to contribute you'll need an account on github and you'll need to learn how to use git. If you've used Subversion (svn) or Perforce (p4) or CVS in there's a learning curve to git. It's a distributed version control system and as such works quite differently than those older style systems. Once you get used to it you'll likely find it very nice but expect at least some amount of learning.

Recommended reading for learning git

Setting up for github

Go to

In the top right area pick "Fork" (login and/or make an account if you're not logged in)


This gives you a personal copy of the repo on github. Instructions for setting up git are here.

Assuming you already have git setup...

In a terminal type (replace <username> with your user name)

   git clone<username>/WebGL.git   
   (will require name and password)


   git clone<username>/WebGL.git
   (requires ssh keys. see

You now have a local copy of your github copy of WebGL.


   cd WebGL
   git remote add upstream git://

This makes an alias, "upstream", for the official repo. There is already an alias, "origin", for your github repo.

Contributing a Change

A common workflow is to use git with branches. Don't get git branches confused with SVN or P4 branches. Git branches are a completely different beast.

Lets say you want to fix the issue that we use green for tests and green passes RGB or BGR. You'd do something like this

Go into your project folder.

   cd WebGL

get the latest from the official version (upstream)

   git fetch upstream master

make a new branch that contains the latest from the master branch from upstream

   git checkout -b change-green-to-blue upstream/master

Note: if this command fails with an error like the following:

   fatal: git checkout: updating paths is incompatible with switching branches.
   Did you intend to checkout 'upstream/master' which can not be resolved as commit?

Then execute the following command:

   git fetch upstream

..make some edits...

add any new files you created

   git add somenewfile.html

add all the files you edited. Unlike svn, git doesn't automatically commit everything you edited. The "-a" (for all) tells git to commit everything that has been edited.

   git commit -a

This only commits the files locally on your personal computer. Push your new branch to YOUR github repo (origin).

  git push origin change-green-to-blue

This will push your "change-green-to-blue" branch to your github.

Now go to github '<username>/WebGL' and in the left area you should see a button "branch:master". Click it and pick your branch


In the top right area pick "Pull Request".


Check the settings are correct. You'll be asking KhronosGroup/WebGL master (left) to pull in your changes from "<username>/WebGL" change-green-to-blue


Type a message and submit.

At this point someone on the WebGL team will hopefully review your pull request.

Handling requested changes

If you are asked to make changes follow these steps to update your submission

Switch to the branch of the pull request you want to edit

   git checkout change-green-to-blue

...edit the files...

Commit the files locally

   git commit -a 

Push your changes up to github

   git push origin change-green-to-blue

Go back to the pull request on github and add a comment that you've uploaded the changes.

It is usually preferred that a pull request contain only a single commit, unless the commit history is significant. To avoid creating a new commit you can instead run:

   git commit -a --amend

or, if you already have multiple commits on your branch, you can run

   git rebase -i

and squash the subsequent commits into the first one.

If you use either of these techniques you will usually find there's a conflict between your local branch and the one you pushed to Github for your pull request. In this case use:

   git push origin change-green-to-blue --force

to update your pull request.

Updating a branch to the latest version

To pull in the latest changes into a branch. First commit your changes if you have any

    git commit -a

Then fetch the latest changes from the official repo (upstream)

    git pull upstream master

Make any edits you'd like the make then push it up to your github repo

   git push origin change-green-to-blue

Delete old branches

Once your pull request has been merged into the main branch you can delete the branch both locally and on github

Switch to some branch other than the one you want to delete. The `master` branch, the branch that was created when you first cloned your repo will do

   git checkout master

Delete the local branch

   git branch -D change-green-to-blue

Delete the branch on github

   git push origin :change-green-to-blue