Tuesday, December 1, 2015

Tipps and Tricks creating pull requests for uDig

First, we love fixes and improvements for functionality and stability!

Second, we need you to make uDig better!

What is a pull request for?

We are allowed to host our source code at Github. Github introduced pull requests to "[..] review the set of changes, discuss potential modifications, and even push follow-up commits if necessary [..]". It helps us to accept patches and discuss approaches directly with code fragments.

Since uDig moved to LocationTech, which is a Industry Working Group of Eclipse Foundation, the project is following their committer guidelines. Eclipse Administrations set up few checks for pull requests to verify:
  • if the committer have signed a CLA at Eclipse
  • if the commit has valid Signed-off-by footers

What is required?

To create pull requests its required to create an Github account. Its also necessary that you've forked uDig.

You should be familiar with Eclipse IDE and have successfully build uDig on your machine. Great!

How to provide a bugfix?

Following the best practices you should create a branch in your working copy. If you like to create a bugfix for an exiting release, please discuss at the mailing list where to start from. If you fix is for future releases, please create a branch from master, e.g. upd-gt-14:
git checkout -b upd-gt-14
Now you can fix the bug.

Whenever you like to commit something, please use -s option. to sign off on commit:
git commit -s -m "upgrade to GeoTools 14.1"
If you are done, its time to share your improvement. Two steps are required to get it into core codebase.

Push your work 

To get others in position to review and accept changes you necessary to publish your work. We are following the common guidelines, where LocationTech's repository is upstream and your fork is origin repository. Push your local branch to your fork
git push upd-gt-14 origin

Create a pull request

Open the repository URL of your fork in a browser and navigate to recently pushed branch. To create a pull request you can hit the green button or click on the link "pull request"

This leads to the following screen where you can add comments and finally create the pull request against the LocationTech's repository.

What if..?

I've already created a pull request but forgot to sign off on commits

The easiest way is to reset your work and commit again, the example down below just demonstrates how to change the last commit on your branch.

NOTE: this is not recommend for master-branch if a commit pushed to LocationTech's repository already!
git reset HEAD^1
After that you have local changes in your working copy you can commit again. Once committed correctly with -s option again please use push command with the force option -f
git push -f upd-gt-14 origin
 This rewrites history but doesn't break anything.

I have lots of commits and like to get it into one

Thats fine and helps a lot to identify and deal with changes later (merging, cherry-picking, etc). Just use rebase command in interactive mode and mark commits to squash into a single one. Please consult git docs for details. After successfully rewrite use force option for git push like mentioned above. 
git reset -i

Wednesday, February 11, 2015

uDig 1.5.0.RC1 Released

The uDig community is pleased to release uDig 1.5.0.RC1. 

Release Details

New Features

This release supports a couple new features:
  • The web view down points to a GitHub page (rather than a wiki page). Thanks to Frank for this work.
  • The style editor now supports arrows (as shown in the above map). Thanks to Emily and Refractions for this work.
  • Packages have been changed to org.locationtech.udig allowing SDK developers to migrate at this time (see below).


Internally the package structure and extensions have changed from net.refractions.udig to org.locationtech.udig. This blog post describes how to setup a development environment and update your plugin accordingly.

Target Platform and Environment

For instructions on using the project straight from GitHub (and building from Eclipse or Maven) see the project README.
We also provide a uDig 1.5.0.RC1 SDK as a stand-alone target platform:
1. Download the SDK
2. Unzip the SDK into a udig-sdk folder.
3. Open up Windows > Preferences and navigate to the Target Platform page
4. Set the target platform to the location of your udig-sdk folder. This will take a few moments while the folder contents are scanned.
As a standalone target platform you can develop uDig with a recent version of Eclipse (uDig no longer depends on your development environment when running). The target platform also includes the JAI and ImageIO bundles which previously were installed as JRE Extensions.
Thanks to Frank for these ease-of-use improvements for uDig developers.

Dependency and Extension Point Migration

At a high-level your plugins must be updated to use the org.locationtech.udig packages and extensions. This can be accomplished with a search and replace, but we will take the time to point out strategies for updating a few specific files.
You can turn off eclipse automatic build when performing these changes to save time.


Required Bundles (Require-Bundle) and imported Packages (Import-Package) in MANIFEST.MF files should reflect the namespace schange as well. Its a simple search and replace within Eclipse (Search -> File...):
Click Replace... to change to new namespace:

Extension Points

Extension definitions based on uDig Extension Points have to be updated. Search for net.refractions.udig in your plugin.xml and feature.xml files and replace the string with org.locationtech.udig

Source Code Migration

With the build environment fixed up we can now move on to updating your source code.
You can turn on eclipse automatic build now, a lot of compile errors are expected after re-compilation against the new udig-sdk target-platform.
This time we can perform the same search and replace on "*.java" files. This should fix the vast majority of problems (as it updates both imports and any extension point references you happened to make use of in your Java code).
If any package import errors remain, click with right mouse on the project and hit Source and Organize Imports.
The uDig 1.5.0.RC1 is built using GeoTools 11.2. The GeoTools project provides an upgrade guide for those using a prior version of the library.

Looking Ahead

If you have any problems with the current udig-sdk or like to ask something we didn't addressed in this post feel free to contact us:
The 2.0.0 Release expects no further API change, its only focus is the transition to Eclipse Luna (a branch is available for developers here).