Contributing a new feature or fix: Difference between revisions

From JogampWiki
Jump to navigation Jump to search
(Created page with '= Overview = Contributing a new feature or bug fix is a bit more involved than just building JOGL. The mai difference is that instead of pulling the code from the canonical repo…')
 
No edit summary
Line 1: Line 1:
= Overview =
= Overview =


Contributing a new feature or bug fix is a bit more involved than just building JOGL. The mai difference is that instead of pulling the code from the canonical repository, you need to fork it, then pull it from your own repository. This lets us use the GitHub infrastructure to share code between JOGL developers.
Contributing a new feature or bug fix is a bit more involved than just building JOGL. The main difference is that instead of pulling the code from the canonical repository on GitHub, you need to fork it, then pull it from your own repository. You create a local branch to hold your changes, then make your changes to it. Finally you push the change branch back to your repository, then create a "pull request" on GitHub for the lead developer to review.


You should already have built JOGL before this, so you're sure Git and all the other tools are set up and working correctly.
You should already have built JOGL at least once before this, so you're sure Git and all the other tools are set up and working correctly.


= Create a free GitHub account =
= Create a free GitHub account =


Go to http://github.com/ and create a free GitHub account. This gives your code a place to live.
Go to http://github.com/ and create a free GitHub account. We use GitHub's infrastructure to share code between developers and manage pull requests.


= Generate new (or use existing) SSH keys =
= Generate new (or use existing) SSH keys =
Line 13: Line 13:
You'll use these keys to access your GitHub code repositories.
You'll use these keys to access your GitHub code repositories.


* To generate keys, see http://help.github.com/msysgit-key-setup/
* To generate keys, see http://help.github.com/msysgit-key-setup/.
* If you already have RSA keys in an .ssh directory, you can just enter one of them into GitHub.
* If you already have RSA keys in an .ssh directory, you can just enter one of them into GitHub.
* To test, type "ssh git@github.com" and enter your passphrase at the prompt. It should say "You've successfully authenticated, but GitHub does not provide shell access. Connection to github.com closed."
* To test, type "ssh git@github.com" and enter your passphrase at the prompt. It should say "You've successfully authenticated, but GitHub does not provide shell access. Connection to github.com closed."
Line 19: Line 19:
= Set your username and email in Git global settings =
= Set your username and email in Git global settings =


This is so your changes to the code will be attributed to you correctly.
This is needed so your changes to the code will be attributed to you correctly.


* Open a shell
* Open a shell
Line 25: Line 25:
* Type this: git config --global user.email "someone@wherever.com"
* Type this: git config --global user.email "someone@wherever.com"


= Fork gluegen and jogl projects on Github =


This creates your initial copies of the code repositories, and gives you a place to push your changes to.
You can check the current values of these settings by typing "git config --global user.name" and "git config --global user.email".
 
= Fork the gluegen and jogl projects on GitHub =
 
This creates your initial copies of the code repositories, and gives you a place to push your change branches to.


* See http://help.github.com/forking/ for instructions
* See http://help.github.com/forking/ for instructions

Revision as of 00:58, 11 January 2011

Overview

Contributing a new feature or bug fix is a bit more involved than just building JOGL. The main difference is that instead of pulling the code from the canonical repository on GitHub, you need to fork it, then pull it from your own repository. You create a local branch to hold your changes, then make your changes to it. Finally you push the change branch back to your repository, then create a "pull request" on GitHub for the lead developer to review.

You should already have built JOGL at least once before this, so you're sure Git and all the other tools are set up and working correctly.

Create a free GitHub account

Go to http://github.com/ and create a free GitHub account. We use GitHub's infrastructure to share code between developers and manage pull requests.

Generate new (or use existing) SSH keys

You'll use these keys to access your GitHub code repositories.

  • To generate keys, see http://help.github.com/msysgit-key-setup/.
  • If you already have RSA keys in an .ssh directory, you can just enter one of them into GitHub.
  • To test, type "ssh git@github.com" and enter your passphrase at the prompt. It should say "You've successfully authenticated, but GitHub does not provide shell access. Connection to github.com closed."

Set your username and email in Git global settings

This is needed so your changes to the code will be attributed to you correctly.

  • Open a shell
  • Type this: git config --global user.name "Your Name"
  • Type this: git config --global user.email "someone@wherever.com"


You can check the current values of these settings by typing "git config --global user.name" and "git config --global user.email".

Fork the gluegen and jogl projects on GitHub

This creates your initial copies of the code repositories, and gives you a place to push your change branches to.

Clone gluegen and jogl locally from your forks

This creates your local working copy of the code.

  • Open a new shell and cd to where you want your repositories
  • Type these commands (they'll require your SSH passphrase)
    • To get gluegen: git clone git@github.com:YourGitHubName/gluegen.git gluegen
    • To get jogl: git clone git@github.com:YourGitHubName/jogl.git jogl

Build the projects

This works just like the build process discussed in "Building JOGL on the command line".

  • cd to gluegen/make, type "ant clean", then type "ant"
  • cd to jogl/make, type "ant clean", then type "ant"

Create a bug report at https://jogamp.org/bugzilla/

This gives you a bug number, which is good to name your code branches with.

NOTE: There's currently a bug the Bugzilla "Log In" link. You can click it and type your login and password, but it doesn't log you in.

So instead of clicking the "Log In" link, click the "New" link, and log in on the page that says "I need a legitimate login and password to continue". You'll need to type your full email address, then your password.

Create branch for fix

  • cd jogl
  • git branch bug_xxx
  • git checkout bug_xxx

Change files, test, and commit

  • git status (shows modified files)
  • git commit -a -v (commits all modified files, lets you type commit message)

Push branch back to Github

  • git push origin bug_xxx

Send pull request on Github

  • Instructions on http://help.github.com/pull-requests/
  • Go to your project on Github
  • Switch branch to bug_xxx
  • Press "Pull Request" button
  • Type comment, check diffs
  • Press "Send pull request"

Wait for your pull request to be accepted

This may take a while, depending on how busy the lead developer is. Also, the lead may ask you to change some aspects of your commits if they don't fit in with other code or don't work during regression testing.

When your pull request is accepted, update the bug status to "Resolved" on Bugzilla!

Retrieved from "https://jogamp.org/wiki/index.php?title=Contributing_a_new_feature_or_fix&oldid=320"