Contributing a new feature or fix

Overview

Contributing a new feature or bug fix to a JogAmp project is a bit more involved than just building it. 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 module maintainer to review your changes.

I'll use JOGL as an example below, but this information applies to other JogAmp projects too. You can find them in our code repositories.

You should already have built the JogAmp project you want to contribute to on the command line or in Eclipse at least once before this, so you're sure Git and all the other tools are set up and working correctly.

Please respect copyright law

When contributing to a JogAmp project, please be sure not to include any code or data that you can't legally donate to the Jogamp community. So for example, you shouldn't cut and paste code from some other commercial or open-source project. This could put its JogAmp's own open-source status in jeopardy, and would require painstaking effort to remove.

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.

• See http://help.github.com/forking/ for instructions.
• Log into GitHub.
• Go to https://github.com/sgothel/gluegen, then press the "Fork" button.
• Go to https://github.com/sgothel/jogl, then press the "Fork" button.

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: Your Bugzilla login is the full email address you used to create an account on the JogAmp forum, with the same 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 source files

This is the code editing process. Use your favorite text editor or IDE to make your contribution. Make sure to put the same Jogamp community copyright notice at the top as in all the other source code files.

If you're editing existing code files, please be considerate. Don't make needless whitespace changes, and try to use the same style as the existing code. This makes the module maintainer's job easier, and makes it more likely your changes will be accepted.

Create a new unit test

Whether fixing a bug or contributing a new feature, you should always create a new unit test to ensure that your contribution works properly. This unit test will also become part of the test suite that's run on every new contribution, to make sure that future changes don't undo your bug fix or break your feature.

You can see an example of a unit test at jogl/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java.

The filename of a unit test for a bug should also contain the Bugzilla ticket number, for example "TestGrayTextureFromFileAWTBug417.java".

Test file names need to start with "Test", and should have "AWT" or "NEWT" somewhere in the name so the Ant build will see them.

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/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".

Run test suite and commit

Before you commit your changes, your modified branch should pass all the unit tests in the suite, both your new tests and the current ones.

To run all the tests in the suite, cd to jogl/make and type ant junit.run. Make sure that any new unit tests you added are run as part of this suite.

The following Git commands are useful when you're ready to commit your changes:

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

Each commit should contain only one bug fix or new feature. Avoid combining lots of different changes into one giant commit, because that makes it difficult for the module maintainer to review your changes and accept them quickly. The ideal commit changes the bare minimum number of lines needed to fix a bug or add a feature.

Push branch back to Github

Once you're done coding, testing, and committing, 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 module 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.
  • Make sure you're not committing any files that have extraneous changes in them that aren't part of your fix or enhancement.
• Press the "Send pull request" button.
• More instructions are at http://help.github.com/pull-requests/

Invite feedback on your new feature or fix

You can let others know about your changes on the Jogamp forum. This is useful to let people know about upcoming changes, and to keep them from duplicating your effort without knowing.

If you include the URL of your pull request, people can comment on it on GitHub too.

Wait for your pull request to be accepted

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