Contributing a new feature or fix - Revision history

Xranby: /* Create a new unit test */ removed nativewindow.all.jar newt.all.jar and rename jogl.all.jar jogl.test.jar -> jogl-all.jar jogl-test.jar

2013-03-02T21:33:10Z

Create a new unit test: removed nativewindow.all.jar newt.all.jar and rename jogl.all.jar jogl.test.jar -> jogl-all.jar jogl-test.jar

← Older revision		Revision as of 23:33, 2 March 2013
Line 97:		Line 97:

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

Wwalker: Fixed to reflect Bugzilla login fix

2011-02-26T22:43:35Z

Fixed to reflect Bugzilla login fix

← Older revision		Revision as of 00:43, 27 February 2011
Line 68:		Line 68:
	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.		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.~~		NOTE: Your Bugzilla login is the full email address you used to create an account on the JogAmp forum, with the same password.

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

Wwalker: Formatting

2011-02-05T23:41:31Z

Formatting

← Older revision		Revision as of 01:41, 6 February 2011
Line 20:		Line 20:

	* 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 <tt>.ssh</tt> directory, you can just enter one of them into GitHub.
	* 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."		* 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."

Wwalker: Generalized to other JogAmp projects

2011-01-22T15:26:01Z

Generalized to other JogAmp projects

← Older revision		Revision as of 17:26, 22 January 2011
Line 1:		Line 1:
	= Overview =		= 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 and Contacts#Maintainer\|module maintainer]] to review your changes.		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 [[Maintainer and Contacts#Maintainer\|module maintainer]] to review your changes.

	You should already have built ~~JOGL~~ [[Building JOGL on the command line\|on the command line]] or [[Building JOGL in Eclipse\|in Eclipse]] at least once before this, so you're sure Git and all the other tools are set up and working correctly.		I'll use JOGL as an example below, but this information applies to other JogAmp projects too. You can find them in our [[Jogamp SCM Repositories\|code repositories]].

			You should already have built the JogAmp project you want to contribute to [[Building JOGL on the command line\|on the command line]] or [[Building JOGL in Eclipse\|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 =		= Please respect copyright law =

	When contributing to ~~JOGL~~, 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 ~~into JOGL~~. This could put its ~~JOGL~~'s own open-source status in jeopardy, and would require painstaking effort to remove.		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 =		= Create a free GitHub account =

Wwalker: Added links to building JOGL pages

2011-01-22T15:16:39Z

Added links to building JOGL pages

← Older revision		Revision as of 17:16, 22 January 2011
Line 3:		Line 3:
	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 and Contacts#Maintainer\|module maintainer]] to review your changes.		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 and Contacts#Maintainer\|module 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.		You should already have built JOGL [[Building JOGL on the command line\|on the command line]] or [[Building JOGL in Eclipse\|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 =		= Please respect copyright law =

Wwalker at 15:57, 11 January 2011

2011-01-11T15:57:13Z

← Older revision		Revision as of 17:57, 11 January 2011
Line 133:		Line 133:
	* Press the "Send pull request" button.		* Press the "Send pull request" button.
	* More instructions are at http://help.github.com/pull-requests/		* 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 [http://jogamp.org/forum.html 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 =		= Wait for your pull request to be accepted =

Wwalker at 15:51, 11 January 2011

2011-01-11T15:51:02Z

Wwalker at 15:43, 11 January 2011

2011-01-11T15:43:21Z

← Older revision		Revision as of 17:43, 11 January 2011
Line 112:		Line 112:
	* <tt>git status</tt> (shows modified files)		* <tt>git status</tt> (shows modified files)
	* <tt>git commit -a -v</tt> (commits all modified files, lets you type commit message)		* <tt>git commit -a -v</tt> (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 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 =		= Push branch back to Github =
Line 128:		Line 130:
	* Type a comment, and check the diffs.		* 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 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.		* Press the "Send pull request" button.
	* More instructions are at http://help.github.com/pull-requests/		* More instructions are at http://help.github.com/pull-requests/

Wwalker at 15:37, 11 January 2011

2011-01-11T15:37:48Z

← Older revision		Revision as of 17:37, 11 January 2011
Line 90:		Line 90:
	You can see an example of a unit test at [https://github.com/sgothel/jogl/blob/master/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java jogl/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java].		You can see an example of a unit test at [https://github.com/sgothel/jogl/blob/master/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java jogl/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java].

	A unit test for a bug should also contain the Bugzilla ticket number, for example "TestGrayTextureFromFileAWTBug417.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.		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.

Wwalker at 15:34, 11 January 2011

2011-01-11T15:34:38Z

← Older revision		Revision as of 17:34, 11 January 2011
Line 78:		Line 78:
	* Type <tt>git checkout bug_xxx</tt>		* Type <tt>git checkout bug_xxx</tt>

	= Change files~~, test, and commit~~ =		= Change source files =

	This is the code editing process. ~~The following Git commands are useful:~~		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.

	* <tt>git status</tt> (shows modified 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 maintainer's job easier, and makes it more likely your changes will be accepted.
	* <tt>git commit -a ~~-v<~~/~~tt> (commits all modified files~~, ~~lets you type commit message)~~
			= 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 [https://github.com/sgothel/jogl/blob/master/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java jogl/src/test/com/jogamp/opengl/test/junit/jogl/demos/gl2/gears/TestGearsAWT.java].

			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:		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 <tt>jogl/build</tt> directory, you can run a single unit test like this:

	<tt>		<tt>
Line 92:		Line 101:

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

			= 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 <tt>jogl/make</tt> and type <tt>ant junit.run</tt>. 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:

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

	= Push branch back to Github =		= 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:		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:

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

← Older revision		Revision as of 17:51, 11 January 2011
Line 1:		Line 1:
	= Overview =		= 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.		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 and Contacts#Maintainer\|module 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.		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.
Line 82:		Line 82:
	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.		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 maintainer's job easier, and makes it more likely your changes will be accepted.		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 [[Maintainer and Contacts#Maintainer\|module maintainer's]] job easier, and makes it more likely your changes will be accepted.

	= Create a new unit test =		= Create a new unit test =
Line 113:		Line 113:
	* <tt>git commit -a -v</tt> (commits all modified files, lets you type commit message)		* <tt>git commit -a -v</tt> (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 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.		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 [[Maintainer and Contacts#Maintainer\|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 =		= Push branch back to Github =
Line 123:		Line 123:
	= Send pull request on Github =		= Send pull request on Github =

	With your branch available on GitHub, you can finally submit a pull request to the maintainer.		With your branch available on GitHub, you can finally submit a pull request to the [[Maintainer and Contacts#Maintainer\|module maintainer]].

	* Go to your project on Github.		* Go to your project on Github.
Line 136:		Line 136:
	= Wait for your pull request to be accepted =		= 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.		This may take a while, depending on how busy the [[Maintainer and Contacts#Maintainer\|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!		When your pull request is accepted, update the bug status to "Resolved" on Bugzilla!