Contributing a new feature or fix: Difference between revisions

From JogampWiki
Jump to navigation Jump to search
No edit summary
(Fixed command formatting)
Line 15: Line 15:
* 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 <tt>ssh git@github.com<tt> 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 =
= Set your username and email in Git global settings =
Line 22: Line 22:


* Open a shell.
* Open a shell.
* Type this: git config --global user.name "Your Name"
* Type <tt>git config --global user.name "Your Name"</tt>
* Type this: git config --global user.email "someone@wherever.com"
* Type <tt>git config --global user.email "someone@wherever.com"</tt>




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


= Fork the gluegen and jogl projects on GitHub =
= Fork the gluegen and jogl projects on GitHub =
Line 46: Line 46:
* Open a new shell and cd to where you want your repositories.
* Open a new shell and cd to where you want your repositories.
* Type these commands (they'll require your SSH passphrase).
* Type these commands (they'll require your SSH passphrase).
** To get gluegen: git clone git@github.com:YourGitHubUsername/gluegen.git gluegen  
** To get gluegen: <tt>git clone git@github.com:YourGitHubUsername/gluegen.git gluegen</tt>
** To get jogl: git clone git@github.com:YourGitHubUsername/jogl.git jogl  
** To get jogl: <tt>git clone git@github.com:YourGitHubUsername/jogl.git jogl</tt>


= Build the projects =
= Build the projects =
Line 53: Line 53:
This works just like the build process discussed in [[Building JOGL on the command line|"Building JOGL on the command line"]].
This works just like the build process discussed in [[Building JOGL on the command line|"Building JOGL on the command line"]].


* cd to gluegen/make, type "ant clean", then type "ant".
* cd to <tt>gluegen/make</tt>, type <tt>ant clean</tt>, then type <tt>ant</tt>.
* cd to jogl/make, type "ant clean", then type "ant".
* cd to <tt>jogl/make</tt>, type <tt>ant clean</tt>, then type <tt>ant</tt>.


= Create an enhancement request or bug report =
= Create an enhancement request or bug report =
Line 70: Line 70:
This keeps your changes together in a form that's easy to push back to the server. Putting your changes in a branch also lets you quickly switch between it and any other branches you may be working on at the same time.
This keeps your changes together in a form that's easy to push back to the server. Putting your changes in a branch also lets you quickly switch between it and any other branches you may be working on at the same time.


* cd jogl  
* cd to <tt>jogl</tt>
* git branch bug_xxx  
* Type <tt>git branch bug_xxx</tt>
* git checkout bug_xxx  
* Type <tt>git checkout bug_xxx</tt>


= Change files, test, and commit =
= Change files, test, and commit =
Line 78: Line 78:
This is the code editing process. The following Git commands are useful:
This is the code editing process. The following Git commands are useful:


* git status (shows modified files)  
* <tt>git status</tt> (shows modified files)  
* git commit -a -v (commits all modified files, lets you type commit message)  
* <tt>git commit -a -v</tt> (commits all modified files, lets you type commit message)  


You can run individual JUnit tests either from the command line or from within Eclipse. From the Linux command line, if you're in the jogl/build directory, you can run a single unit test like this:
You can run individual JUnit tests either from the command line or from within Eclipse. From the Linux command line, if you're in the jogl/build directory, you can run a single unit test like this:


java -Djava.awt.headless=false \
<tt>
-Djava.library.path="lib" \
java -Djava.awt.headless=false -Djava.library.path="lib" -cp "../../gluegen/make/lib/junit.jar:$ANT_HOME/lib/ant.jar:$ANT_HOME/lib/ant-junit.jar:jar/gluegen-rt.jar:jar/nativewindow.all.jar:jar/newt.all.jar:jar/jogl.all.jar:jar/jogl.test.jar" com.jogamp.opengl.test.junit.jogl.texture.TestGrayTextureFromFileAWTBug417
-cp "../../gluegen/make/lib/junit.jar:$ANT_HOME/lib/ant.jar:$ANT_HOME/lib/ant-junit.jar:jar/gluegen-rt.jar:jar/nativewindow.all.jar:jar/newt.all.jar:jar/jogl.all.jar:jar/jogl.test.jar" \
</tt>
com.jogamp.opengl.test.junit.jogl.texture.TestGrayTextureFromFileAWTBug417


From within Eclipse, simply right-click the test's Java file in the Package Explorer and select "Debug As > JUnit Test".
From within Eclipse, simply right-click the test's Java file in the Package Explorer and select "Debug As > JUnit Test".
Line 94: Line 93:
Once you're done coding and testing, you need to push your new branch back up to GitHub so others can see it. Here's the command:
Once you're done coding and testing, you need to push your new branch back up to GitHub so others can see it. Here's the command:


* git push origin bug_xxx  
* <tt>git push origin bug_xxx</tt>


= Send pull request on Github =
= Send pull request on Github =

Revision as of 15:45, 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 work on your own forked repository. When you're done, you submit a "pull request" on GitHub for the maintainer to review your changes.

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 to 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 git config --global user.name "Your Name"
  • Type 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.


Now when you go to http://github.com/, you'll see gluegen and jogl under "Your Repositories" on the right.

Clone gluegen and jogl 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:YourGitHubUsername/gluegen.git gluegen
    • To get jogl: git clone git@github.com:YourGitHubUsername/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 an enhancement request or bug report

Log into https://jogamp.org/bugzilla/ and create an enhancement request or bug report.

This gives you a Bugzilla ticket number, which is good to name your code branches with. A new feature can be entered into Bugzilla as ticket with severity set to "enhancement" instead of "critical", "major", et cetera.

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 a branch for your feature or fix

This keeps your changes together in a form that's easy to push back to the server. Putting your changes in a branch also lets you quickly switch between it and any other branches you may be working on at the same time.

  • cd to jogl
  • Type git branch bug_xxx
  • Type git checkout bug_xxx

Change files, test, and commit

This is the code editing process. The following Git commands are useful:

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

You can run individual JUnit tests either from the command line or from within Eclipse. From the Linux command line, if you're in the jogl/build directory, you can run a single unit test like this:

java -Djava.awt.headless=false -Djava.library.path="lib" -cp "../../gluegen/make/lib/junit.jar:$ANT_HOME/lib/ant.jar:$ANT_HOME/lib/ant-junit.jar:jar/gluegen-rt.jar:jar/nativewindow.all.jar:jar/newt.all.jar:jar/jogl.all.jar:jar/jogl.test.jar" com.jogamp.opengl.test.junit.jogl.texture.TestGrayTextureFromFileAWTBug417

From within Eclipse, simply right-click the test's Java file in the Package Explorer and select "Debug As > JUnit Test".

Push branch back to Github

Once you're done coding and testing, you need to push your new branch back up to GitHub so others can see it. Here's the command:

  • git push origin bug_xxx

Send pull request on Github

With your branch available on GitHub, you can finally submit a pull request to the maintainer.

  • Go to your project on Github.
  • Hover your mouse over the "Switch Branches" button, and select "bug_xxx" from the list.
  • Press "Pull Request" button.
  • Type a comment, and check the diffs.
    • Make sure not to submit a pull request that includes extra whitespace changes; these make it hard to identify the real code changes.
  • Press the "Send pull request" button.
  • More instructions are at http://help.github.com/pull-requests/

Wait for your pull request to be accepted

This may take a while, depending on how busy the maintainer is. Also, the maintainer 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!