Contribution Guide
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.
Environment
The development tools with minimum versions that are used by the NatTable team are:
- JDK 1.8
- Eclipse 4.17
- Maven 3.6.3 with Tycho 2.0.0
- Git
- Gerrit
Gerrit server configuration
Obtaining sources and importing projects into Eclipse
Cloning via command line
Change to the directory where you want to store the local working copy of the NatTable repository (NATTABLE_REPO).
Clone the repository to that directory by executing the following Git command:
git clone ssh://<user_id>@git.eclipse.org:29418/nattable/org.eclipse.nebula.widgets.nattable
After that, import the projects into Eclipse
- File -> Import
- General -> Existing Projects into Workspace
- Next
- Select root directory: (NATTABLE_REPO/org.eclipse.nebula.widgets.nattable)
- Finish
Cloning via EGit
First, verify that the default repository folder as set on the main Git preference page is to your liking.
Then, clone the repository and import the projects:
- File -> Import
- Git -> Projects from Git
- Select Clone URI
- Enter the URI
ssh://<user_id>@git.eclipse.org:29418/nattable/org.eclipse.nebula.widgets.nattable - Import existing projects into the workspace from the newly created working directory
Source code organization
The NatTable source is divided into the following main projects:
- org.eclipse.nebula.widgets.nattable.core - NatTable Core code
- org.eclipse.nebula.widgets.nattable.core.test - NatTable Core test code
- org.eclipse.nebula.widgets.nattable.extension.e4 - NatTable extensions for Eclipse 4
- org.eclipse.nebula.widgets.nattable.extension.glazedlists - NatTable extensions for GlazedLists
- org.eclipse.nebula.widgets.nattable.extension.glazedlists.test - NatTable extensions for GlazedLists tests
- org.eclipse.nebula.widgets.nattable.extension.nebula - NatTable extensions for Nebula
- org.eclipse.nebula.widgets.nattable.extension.poi - NatTable extensions for Apache POI
- org.eclipse.nebula.widgets.examples - NatTable example application containing several examples
- org.eclipse.nebula.widgets.examples.e4 - NatTable examples for Eclipse 4
- org.eclipse.nebula.widgets.examples.e4.product - NatTable examples application as Eclipse 4 application
In addition there are also various feature projects necessary for release engineering. All of these projects are packaged as Eclipse plugins/OSGi bundles.
Development IDE Configuration
Tools
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.
Java Requirements
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.
Dependencies
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.
- Open the target-platform project
- Open the target-platform.target file (this may take a while as it downloads the indexes of the p2 repositories the target platform refers to)
- In the resulting editor, click on the Set as Target Platform link at the top right (this may also take a while)
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.
API Baseline
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 gravity of the changes you are making (major, minor, micro) according to OSGi semantic versioning
The baseline you have to set is provided in the folder api-baseline.
Open the workspace preferences (Window > Preferences) and head to Plug-in Development > API Baselines. There, hit Add Baseline... to define a new baseline. Choose any name you like (the version of the release the baseline represents might be suitable, i.e. NatTable 2.0). Then, press Browse... and choose the api-baseline folder within the NatTable git repository. Press Finish and apply the changes. This should trigger a workspace build.
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 NatTable 1.4 baseline, major API changes will be marked as errors in the IDE). More information about the API tooling can be found here.
Note, that you should aspire to make changes of the magnitude micro. These can be released in a Bugfix-Release, while minor changes (new APIs) need a more elaborate release process. Currently, major changes will be generally rejected.
Workspace Preferences
Ensure to set the text file encoding to UTF-8.
- Window -> Preferences -> General -> Workspace
- Set 'Text file encoding' to 'Other' - 'UTF-8'
Build
The NatTable build is based on pomless Tycho. To build from the command line, you need to execute the following command from the NATTABLE_TRUNK/nattable directory:
mvn clean verify
After the build successfully finished, you will find an Update Site archive in
NATTABLE_TRUNK/nattable/org.eclipse.nebula.widgets.nattable.updatesite/target
that you can use for example in a local target definition.
Contributing Patches
We use Gerrit for reviewing and accepting patches. Please have a look at the Eclipse Gerrit Guide.
- Make small logical changes.
- Provide a meaningful commit message. It should contain the name of the related bug ticket. (See A Note About Git Commit Messages for guidelines.)
- Review and follow the Eclipse Due Diligence Process
Contributing to the NatTable website
To contribute to the website the following repositories need to be cloned:
- git clone ssh://<user_id>@git.eclipse.org:29418/www.eclipse.org/nattable
- git clone ssh://<user_id>@git.eclipse.org:29418/www.eclipse.org/eclipse.org-common
To test locally we recommend a local webserver installation with PHP support, e.g. XAMPP.
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 htdocs directory of XAMPP.
- Open a Windows console as Administrator
- Change directory: <install_dir>\xampp\htdocs
- mklink /D nattable <clone_dir>\nattable
- mklink /D "eclipse.org-common" <clone_dir>\eclipse.org-common
Once the symbolic links are in place, start XAMPP via control center and open localhost/nattable in a browser.