Using Github To Contribute

From WebGL Public Wiki
Revision as of 02:07, 9 October 2021 by Kbr google (talk | contribs) (Rename master branch references to main)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to 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 [email protected]:<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 main

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

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

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/main' 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:main". 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 main (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 the full commit history of the change, so that reviewers can pinpoint changes as they're made. (Reviewers: please use Github's "Squash and Merge" option, in order to keep the commit history clean, and to better link to the pull requests.)

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 main

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 `main` branch, the branch that was created when you first cloned your repo will do

   git checkout main

Delete the local branch

   git branch -D change-green-to-blue

Delete the branch on github

   git push origin :change-green-to-blue