Using Github To Contribute

The Draft WebGL Specification, WebGL extension registry, and the WebGL Conformance Test Suite are hosted on github at http://github.com/KhronosGroup/WebGL

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

• Pro Git Especially please read the first chapter if nothing else.
• try.github.com is an interactive git tutorial
• The Git Parable explains how git works from the ground up one simple step at a time.
• Github help: Specifically articles linked by the 4 icons at the top of the page.
• Stackoverflow.com is a great place to find answers to specific git questions.
• Linus Torvalds' infamous git talk. Maybe not the best for learning but possibly for motivating you to learn (or piss you off depending)

Setting up for github

Go to http://github.com/KhronosGroup/WebGL

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. https://help.github.com/articles/set-up-git.

Assuming you already have git setup...

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

   git clone https://github.com/<username>/WebGL.git   
   (will require name and password)

or

   git clone [email protected]:<username>/WebGL.git
   (requires ssh keys. see https://help.github.com/articles/generating-ssh-keys)

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

Type

   cd WebGL
   git remote add upstream git://github.com/KhronosGroup/WebGL.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 'https://github.com/<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