documentation/contribution_guide.html - gerrit/www.eclipse.org/nattable - Git at Google

 <div id="midcolumn">
 	<h2>Contribution Guide</h2>
 	<div>
 		<p>
 			You can download the source code and contribute bugfixes or enhancements to NatTable.
 			The following information will help you set up your development environment in order to be able to contribute.
 		</p>
 	</div>
 	<div id="doccontent">
 		<div class="chapter">
 			<h3>Environment</h3>
 			<div class="content">
 				<p>The development tools with minimum versions that are used by the NatTable team are:
 					<ul>
 						<li>JDK 1.8</li>
 						<li>Eclipse 4.17</li>
 						<li>Maven 3.6.3 with Tycho 2.0.0</li>
 						<li>Git</li>
 						<li>Gerrit</li>
 					</ul>
 				</p>
 			</div>
 		</div>
 		<div class="chapter">
 			<h3>Gerrit server configuration</h3>
 			<div class="content">
 				To be able to contribute to the project, patches need to be provided via Gerrit. You therefore need a Gerrit account and configure
 				the authentication there. This is explained for example
 				<a href="https://www.vogella.com/tutorials/EclipsePlatformDevelopment/article.html#exericse-eclipse-user-creation-and-gerrit-server-configuration" target="blank">here</a>.
 			</div>
 		</div>
 		<div class="chapter">
 			<h3>Obtaining sources and importing projects into Eclipse</h3>
 			<div class="content">
 				The NatTable sources are hosted in Git. To get the sources you need to clone the repository either via
 				command line or via EGit Eclipse integration.

 				<h4>Cloning via command line</h4>
 				<p>Change to the directory where you want to store the local working copy of the NatTable repository (NATTABLE_REPO).</p>
 				<p>Clone the repository to that directory by executing the following Git command:</p>
 				<p><span class="code">git clone ssh://&lt;user_id&gt;@git.eclipse.org:29418/nattable/org.eclipse.nebula.widgets.nattable</span></p>
 				<p>After that, import the projects into Eclipse</p>
 				<ul>
 				    <li>File -> Import</li>
 				    <li>General -> Existing Projects into Workspace</li>
 				    <li>Next</li>
 				    <li>Select root directory: (NATTABLE_REPO/org.eclipse.nebula.widgets.nattable)</li>
 				    <li>Finish</li>
 				</ul>

 				<h4>Cloning via EGit</h4>
 				<p>First, verify that the default repository folder as set on the main Git preference page is to your liking.</p>
 				<p>Then, clone the repository and import the projects: </p>
 				<ul>
 				    <li>File -> Import</li>
 				    <li>Git -> Projects from Git</li>
 				    <li>Select <i>Clone URI</i></li>
 				    <li>Enter the URI <br>
 				    	<span class="code">ssh://&lt;user_id&gt;@git.eclipse.org:29418/nattable/org.eclipse.nebula.widgets.nattable</span></li>
 				    <li>Import existing projects into the workspace from the newly created working directory </li>
 				</ul>

 				<h4>Source code organization</h4>
 				<p>The NatTable source is divided into the following main projects:
 				<ul>
 					<li>org.eclipse.nebula.widgets.nattable.core - NatTable Core code
 					<li>org.eclipse.nebula.widgets.nattable.core.test - NatTable Core test code
 					<li>org.eclipse.nebula.widgets.nattable.extension.e4 - NatTable extensions for Eclipse 4
 					<li>org.eclipse.nebula.widgets.nattable.extension.glazedlists - NatTable extensions for GlazedLists
 					<li>org.eclipse.nebula.widgets.nattable.extension.glazedlists.test - NatTable extensions for GlazedLists tests
 					<li>org.eclipse.nebula.widgets.nattable.extension.nebula - NatTable extensions for Nebula
 					<li>org.eclipse.nebula.widgets.nattable.extension.poi - NatTable extensions for Apache POI
 					<li>org.eclipse.nebula.widgets.examples - NatTable example application containing several examples
 					<li>org.eclipse.nebula.widgets.examples.e4 - NatTable examples for Eclipse 4
 					<li>org.eclipse.nebula.widgets.examples.e4.product - NatTable examples application as Eclipse 4 application
 				</ul>
 				</p>

 				<p>
 					In addition there are also various feature projects necessary for release engineering.
 					All of these projects are packaged as Eclipse plugins/OSGi bundles.
 				</p>
 			</div>
 		</div>

 		<div class="chapter">
 			<h3>Development IDE Configuration</h3>
 			<div class="content">
 				<h4>Tools</h4>
 				<p>
 					Although not required you might want to install m2e together with the Tycho connector in order
 					to be able to build out of the IDE. This step is optional.
 				</p>

 				<h4>Java Requirements</h4>
 				<p>
 					NatTable Core has a Java 8 and Eclipse Platform 3.5 (Galileo) as minimum requirements,
 					so dependencies to newer Java and platform versions must be avoided. The Nebula extension and the E4 extension
 					have a dependency to Java 8 and Eclipse Neon.
 				</p>

 				<h4>Dependencies</h4>
 				<p>
 					After importing the NatTable projects in Eclipse, they will not compile due to missing dependencies.
 					NatTable provides a target platform definition that should be activated in order to resolve the
 					missing dependencies.
 				</p>

 				<ul>
 				    <li>Open the <i>target-platform</i> project</li>
 				    <li>Open the <i>target-platform.target</i> file
 				    	(this may take a while as it downloads the indexes of the p2 repositories the target platform refers to) </li>
 				    <li>In the resulting editor, click on the <i>Set as Target Platform</i> link at the top right
 				    	(this may also take a while) </li>
 				</ul>

 				<p>
 					After that, the workspace should build cleanly. If not, try Project > Clean... > All.
 					If this also doesn't help open Preferences > Plug-In Development > Target Platform,
 					select the checked target platform and click "Reload..." this will flush PDE's bundle
 					cache and re-download the artifacts listed in the target platform.
 				</p>

 				<h4>API Baseline</h4>
 				<p>
 					After importing the NatTable projects you should setup the API baseline if you intend to make changes to the code.
 					This will help you detect the <i>gravity</i> of the changes you are making (major, minor, micro) according to
 					<a href="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf" target="_blank">OSGi semantic versioning</a>
 				</p>
 				<p>
 					The baseline you have to set is provided in the folder <i>api-baseline</i>.
 				</p>
 				<p>
 					Open the workspace preferences (Window > Preferences) and head to Plug-in Development > API Baselines.
 					There, hit <i>Add Baseline...</i> to define a new baseline. Choose any name you like (the version of the release the baseline
 					represents might be suitable, i.e. <i>NatTable 2.0</i>). Then, press <i>Browse...</i> and choose the api-baseline folder
 					within the NatTable git repository. Press <i>Finish</i> and apply the changes. This should trigger a workspace build.
 				</p>
 				<p>
 					From here on out the API tooling will highlight your code when your changes exceed the current margin given by the
 					snapshot version (e.g. while working on the 1.5 snapshot with the <i>NatTable 1.4</i> baseline, major API changes will
 					be marked as errors in the IDE).
 					More information about the API tooling can be found <a href="http://wiki.eclipse.org/PDE/API_Tools/User_Guide">here</a>.
 				</p>
 				<p>
 					Note, that you should aspire to make changes of the magnitude <i>micro</i>. These can be release in a Bugfix-Release,
 					while <i>minor</i> changes (new APIs) need a more elaborate release process. Currently, <i>major</i> changes will be generally rejected.
 				</p>

 				<h4>Workspace Preferences</h4>
 				<p>
 					Ensure to set the text file encoding to UTF-8.
 					<ul>
 						<li>Window -> Preferences -> General -> Workspace</li>
 						<li>Set 'Text file encoding' to 'Other' - 'UTF-8'</li>
 					</ul>
 				</p>
 			</div>
 		</div>
 		<div class="chapter">
 			<h3>Build</h3>
 			<div class="content">
 				<p>
 				The NatTable build is based on pomless Tycho.
 				To build from the command line, you need to execute the following command from the <i>NATTABLE_TRUNK/nattable</i> directory:</p>

 				<p><span class="code">mvn clean verify</span></p>

 				<p>
 					After the build successfully finished, you will find an Update Site archive in
 				</p>
 				<p>
 					<i>NATTABLE_TRUNK/nattable/org.eclipse.nebula.widgets.nattable.updatesite/target</i>
 				</p>
 				<p>
 					that you can use for example in a local target definition.
 				</p>
 			</div>
 		</div>
 		<div class="chapter">
 			<h3>Contributing Patches</h3>
 			<div class="content">
 				<p>
 					We use Gerrit for reviewing and accepting patches. Please have a look at the
 					<a href="https://wiki.eclipse.org/Gerrit#Doing_Code_Reviews_with_Gerrit">Eclipse Gerrit Guide.</a>
 				</p>
 					<ul>
 						<li> Make small logical changes.</li>
 						<li> Provide a meaningful commit message. It should contain the name of the related bug ticket.
 							(See <a rel="nofollow" class="external text" href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">A Note About Git Commit Messages</a> for guidelines.)</li>
 						<li> Review and follow the Eclipse Due Diligence Process
 							<ul>
 								<li> <a rel="nofollow" class="external free" href="http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php">http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php</a></li>
 								<li> <a rel="nofollow" class="external free" href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf</a></li>
 							</ul>
 						</li>
 					</ul>
 			</div>
 		</div>
 		<div class="chapter">
 			<h3>Contributing to the NatTable website</h3>
 			<div class="content">
 				<p>
 					To contribute to the website the following repositories need to be cloned:</a>
 					<ul>
 						<li><span class="code">git clone ssh://&lt;user_id&gt;@git.eclipse.org:29418/www.eclipse.org/nattable</span></li>
 						<li><span class="code">git clone ssh://&lt;user_id&gt;@git.eclipse.org:29418/www.eclipse.org/eclipse.org-common</span></li>
 					</ul>
 				</p>
 				<p>
 					To test locally we recommend a local webserver installation with PHP support, e.g. <a href="https://www.apachefriends.org/de/index.html" target="_blank">XAMPP</a>.
 				</p>
 				<p>
 					If XAMPP is used, ensure that the two cloned repositories are accessible in the webserver. This can be done for example by
 					setting symbolic links in the <i>htdocs</i> directory of XAMPP.
 					<ul>
 						<li>Open a Windows console as Administrator</li>
 						<li>Change directory: <span class="code">&lt;install_dir&gt;\xampp\htdocs</span></li>
 						<li><span class="code">mklink /D nattable &lt;clone_dir&gt;\nattable</span></li>
 						<li><span class="code">mklink /D "eclipse.org-common" &lt;clone_dir&gt;\eclipse.org-common</span></li>
 					</ul>
 				</p>
 				<p>
 					Once the symbolic links are in place, start XAMPP via control center and open <i>localhost/nattable</i> in a browser.
 				</p>
 			</div>
 		</div>

 	</div>
 </div>
	<div id="midcolumn">
	<h2>Contribution Guide</h2>
	<div>
	<p>
	You can download the source code and contribute bugfixes or enhancements to NatTable.
	The following information will help you set up your development environment in order to be able to contribute.
	</p>
	</div>
	<div id="doccontent">
	<div class="chapter">
	<h3>Environment</h3>
	<div class="content">
	<p>The development tools with minimum versions that are used by the NatTable team are:
	<ul>
	<li>JDK 1.8</li>
	<li>Eclipse 4.17</li>
	<li>Maven 3.6.3 with Tycho 2.0.0</li>
	<li>Git</li>
	<li>Gerrit</li>
	</ul>
	</p>
	</div>
	</div>
	<div class="chapter">
	<h3>Gerrit server configuration</h3>
	<div class="content">
	To be able to contribute to the project, patches need to be provided via Gerrit. You therefore need a Gerrit account and configure
	the authentication there. This is explained for example
	<a href="https://www.vogella.com/tutorials/EclipsePlatformDevelopment/article.html#exericse-eclipse-user-creation-and-gerrit-server-configuration" target="blank">here</a>.
	</div>
	</div>
	<div class="chapter">
	<h3>Obtaining sources and importing projects into Eclipse</h3>
	<div class="content">
	The NatTable sources are hosted in Git. To get the sources you need to clone the repository either via
	command line or via EGit Eclipse integration.

	<h4>Cloning via command line</h4>
	<p>Change to the directory where you want to store the local working copy of the NatTable repository (NATTABLE_REPO).</p>
	<p>Clone the repository to that directory by executing the following Git command:</p>
	<p><span class="code">git clone ssh://<user_id>@git.eclipse.org:29418/nattable/org.eclipse.nebula.widgets.nattable</span></p>
	<p>After that, import the projects into Eclipse</p>
	<ul>
	<li>File -> Import</li>
	<li>General -> Existing Projects into Workspace</li>
	<li>Next</li>
	<li>Select root directory: (NATTABLE_REPO/org.eclipse.nebula.widgets.nattable)</li>
	<li>Finish</li>
	</ul>

	<h4>Cloning via EGit</h4>
	<p>First, verify that the default repository folder as set on the main Git preference page is to your liking.</p>
	<p>Then, clone the repository and import the projects: </p>
	<ul>
	<li>File -> Import</li>
	<li>Git -> Projects from Git</li>
	<li>Select <i>Clone URI</i></li>
	<li>Enter the URI <br>
	<span class="code">ssh://<user_id>@git.eclipse.org:29418/nattable/org.eclipse.nebula.widgets.nattable</span></li>
	<li>Import existing projects into the workspace from the newly created working directory </li>
	</ul>

	<h4>Source code organization</h4>
	<p>The NatTable source is divided into the following main projects:
	<ul>
	<li>org.eclipse.nebula.widgets.nattable.core - NatTable Core code
	<li>org.eclipse.nebula.widgets.nattable.core.test - NatTable Core test code
	<li>org.eclipse.nebula.widgets.nattable.extension.e4 - NatTable extensions for Eclipse 4
	<li>org.eclipse.nebula.widgets.nattable.extension.glazedlists - NatTable extensions for GlazedLists
	<li>org.eclipse.nebula.widgets.nattable.extension.glazedlists.test - NatTable extensions for GlazedLists tests
	<li>org.eclipse.nebula.widgets.nattable.extension.nebula - NatTable extensions for Nebula
	<li>org.eclipse.nebula.widgets.nattable.extension.poi - NatTable extensions for Apache POI
	<li>org.eclipse.nebula.widgets.examples - NatTable example application containing several examples
	<li>org.eclipse.nebula.widgets.examples.e4 - NatTable examples for Eclipse 4
	<li>org.eclipse.nebula.widgets.examples.e4.product - NatTable examples application as Eclipse 4 application
	</ul>
	</p>

	<p>
	In addition there are also various feature projects necessary for release engineering.
	All of these projects are packaged as Eclipse plugins/OSGi bundles.
	</p>
	</div>
	</div>

	<div class="chapter">
	<h3>Development IDE Configuration</h3>
	<div class="content">
	<h4>Tools</h4>
	<p>
	Although not required you might want to install m2e together with the Tycho connector in order
	to be able to build out of the IDE. This step is optional.
	</p>

	<h4>Java Requirements</h4>
	<p>
	NatTable Core has a Java 8 and Eclipse Platform 3.5 (Galileo) as minimum requirements,
	so dependencies to newer Java and platform versions must be avoided. The Nebula extension and the E4 extension
	have a dependency to Java 8 and Eclipse Neon.
	</p>

	<h4>Dependencies</h4>
	<p>
	After importing the NatTable projects in Eclipse, they will not compile due to missing dependencies.
	NatTable provides a target platform definition that should be activated in order to resolve the
	missing dependencies.
	</p>

	<ul>
	<li>Open the <i>target-platform</i> project</li>
	<li>Open the <i>target-platform.target</i> file
	(this may take a while as it downloads the indexes of the p2 repositories the target platform refers to) </li>
	<li>In the resulting editor, click on the <i>Set as Target Platform</i> link at the top right
	(this may also take a while) </li>
	</ul>

	<p>
	After that, the workspace should build cleanly. If not, try Project > Clean... > All.
	If this also doesn't help open Preferences > Plug-In Development > Target Platform,
	select the checked target platform and click "Reload..." this will flush PDE's bundle
	cache and re-download the artifacts listed in the target platform.
	</p>

	<h4>API Baseline</h4>
	<p>
	After importing the NatTable projects you should setup the API baseline if you intend to make changes to the code.
	This will help you detect the <i>gravity</i> of the changes you are making (major, minor, micro) according to
	<a href="http://www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf" target="_blank">OSGi semantic versioning</a>
	</p>
	<p>
	The baseline you have to set is provided in the folder <i>api-baseline</i>.
	</p>
	<p>
	Open the workspace preferences (Window > Preferences) and head to Plug-in Development > API Baselines.
	There, hit <i>Add Baseline...</i> to define a new baseline. Choose any name you like (the version of the release the baseline
	represents might be suitable, i.e. <i>NatTable 2.0</i>). Then, press <i>Browse...</i> and choose the api-baseline folder
	within the NatTable git repository. Press <i>Finish</i> and apply the changes. This should trigger a workspace build.
	</p>
	<p>
	From here on out the API tooling will highlight your code when your changes exceed the current margin given by the
	snapshot version (e.g. while working on the 1.5 snapshot with the <i>NatTable 1.4</i> baseline, major API changes will
	be marked as errors in the IDE).
	More information about the API tooling can be found <a href="http://wiki.eclipse.org/PDE/API_Tools/User_Guide">here</a>.
	</p>
	<p>
	Note, that you should aspire to make changes of the magnitude <i>micro</i>. These can be release in a Bugfix-Release,
	while <i>minor</i> changes (new APIs) need a more elaborate release process. Currently, <i>major</i> changes will be generally rejected.
	</p>

	<h4>Workspace Preferences</h4>
	<p>
	Ensure to set the text file encoding to UTF-8.
	<ul>
	<li>Window -> Preferences -> General -> Workspace</li>
	<li>Set 'Text file encoding' to 'Other' - 'UTF-8'</li>
	</ul>
	</p>
	</div>
	</div>
	<div class="chapter">
	<h3>Build</h3>
	<div class="content">
	<p>
	The NatTable build is based on pomless Tycho.
	To build from the command line, you need to execute the following command from the <i>NATTABLE_TRUNK/nattable</i> directory:</p>

	<p><span class="code">mvn clean verify</span></p>

	<p>
	After the build successfully finished, you will find an Update Site archive in
	</p>
	<p>
	<i>NATTABLE_TRUNK/nattable/org.eclipse.nebula.widgets.nattable.updatesite/target</i>
	</p>
	<p>
	that you can use for example in a local target definition.
	</p>
	</div>
	</div>
	<div class="chapter">
	<h3>Contributing Patches</h3>
	<div class="content">
	<p>
	We use Gerrit for reviewing and accepting patches. Please have a look at the
	<a href="https://wiki.eclipse.org/Gerrit#Doing_Code_Reviews_with_Gerrit">Eclipse Gerrit Guide.</a>
	</p>
	<ul>
	<li> Make small logical changes.</li>
	<li> Provide a meaningful commit message. It should contain the name of the related bug ticket.
	(See <a rel="nofollow" class="external text" href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">A Note About Git Commit Messages</a> for guidelines.)</li>
	<li> Review and follow the Eclipse Due Diligence Process
	<ul>
	<li> <a rel="nofollow" class="external free" href="http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php">http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php</a></li>
	<li> <a rel="nofollow" class="external free" href="http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf">http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf</a></li>
	</ul>
	</li>
	</ul>
	</div>
	</div>
	<div class="chapter">
	<h3>Contributing to the NatTable website</h3>
	<div class="content">
	<p>
	To contribute to the website the following repositories need to be cloned:</a>
	<ul>
	<li><span class="code">git clone ssh://<user_id>@git.eclipse.org:29418/www.eclipse.org/nattable</span></li>
	<li><span class="code">git clone ssh://<user_id>@git.eclipse.org:29418/www.eclipse.org/eclipse.org-common</span></li>
	</ul>
	</p>
	<p>
	To test locally we recommend a local webserver installation with PHP support, e.g. <a href="https://www.apachefriends.org/de/index.html" target="_blank">XAMPP</a>.
	</p>
	<p>
	If XAMPP is used, ensure that the two cloned repositories are accessible in the webserver. This can be done for example by
	setting symbolic links in the <i>htdocs</i> directory of XAMPP.
	<ul>
	<li>Open a Windows console as Administrator</li>
	<li>Change directory: <span class="code"><install_dir>\xampp\htdocs</span></li>
	<li><span class="code">mklink /D nattable <clone_dir>\nattable</span></li>
	<li><span class="code">mklink /D "eclipse.org-common" <clone_dir>\eclipse.org-common</span></li>
	</ul>
	</p>
	<p>
	Once the symbolic links are in place, start XAMPP via control center and open <i>localhost/nattable</i> in a browser.
	</p>
	</div>
	</div>

	</div>
	</div>