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 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

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)

Github-webgl-fork2.png

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 git@github.com:<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 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 'https://github.com/<username>/WebGL' and in the left area you should see a button "branch:master". Click it and pick your branch

Github-webgl-select-branch.png

In the top right area pick "Pull Request".

Github-webgl-pull-request.png

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

Github-webgl-pull-verification.png

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.

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