PackageDrone/HowTo/Contribute

This page is a short guide on how to contribute to Package Drone:

Helpful links

Here are few helpful links:

• Contributing notes – The CONTRIBUTING.md file from the Package Drone GitHub repository
• Contact page – How to get in contact with the project
• http://packagedrone.org – The blog
• Development introduction – A more formal guide about development
• Eclipse Package Drone – The official entry page at eclipse.org

What you need to bring

In short Package Drone requires a recent Eclipse IDE installation, Java 8 and, at best, a Linux-ish operating system. Recent versions of Ubuntu and Mint are known to work.

Knowledge of OSGi, Eclipse PDE and JEE/JSP will surely help.

Contribute license agreement

Before getting started you should know that if you want to contribute source code, you will need to sign a CLA. In order to do this you need to:

• Create an account at Eclipse.org
• Go to https://projects.eclipse.org/user/sign/cla and fill out the "paperwork"

If you just want to browse the code and experiment a bit, you are free to do so without any CLA. But if you want to contribute code to Package Drone there is no way without a CLA!

Getting ready

There is an automated process for setting up an Eclipse IDE for Package Drone at PackageDrone/Oomph. This should give you a ready-to-run developer setup in minutes.

You should now be able to start a local instance of Package Drone directly from your IDE. Making changes on the code simply require a restart of the application. It is not necessary to start a build manually for testing changes you make.

Console output

At the moment Package Drone is using Eclipse Equinox as OSGi DS implementation. However it seems to have some issues which cause an internal deadlock, including a deadlock resolution by throwing an exception. In the end all services are being created, but you might see a few error messages on the console like the following sample:

!ENTRY org.eclipse.equinox.ds 2 0 2016-02-15 00:23:36.512
!MESSAGE Getting a lock required more than 1000 ms. There might be a synchronization problem in this callstack or just the build/dispose process of some components took too long!
!STACK 0
java.lang.Exception: Debug stacktrace
	at org.eclipse.equinox.internal.ds.InstanceProcess.getLock(InstanceProcess.java:120)
	at org.eclipse.equinox.internal.ds.InstanceProcess.buildComponents(InstanceProcess.java:159)
	at org.eclipse.equinox.internal.ds.Resolver.buildNewlySatisfied(Resolver.java:473)
	at org.eclipse.equinox.internal.ds.Resolver.enableComponents(Resolver.java:217)
	at org.eclipse.equinox.internal.ds.SCRManager.performWork(SCRManager.java:816)
	at org.eclipse.equinox.internal.ds.SCRManager$QueuedJob.dispatch(SCRManager.java:783)
	at org.eclipse.equinox.internal.ds.WorkThread.run(WorkThread.java:89)
	at org.eclipse.equinox.internal.util.impl.tpt.threadpool.Executor.run(Executor.java:70)

You can safely ignore these messages for the moment. Maybe we need to swap out the DS implementation from Equinox to some other implementation like Apache Felix in the future.

What to do next?

If you don't have a task you want to work on right away, you can browse the list of tasks where help is appreciated.

You can check issues with the tag "help wanted" at GitHub or simply follow this link: https://github.com/eclipse/packagedrone/labels/help%20wanted Not all tasks are trivial, so watch out for the "nasty" ones ;-)

If you want to work in this task it is best to indicate this in the GitHub issue so that everybody knows you are working on this. Also if you have to make any design (visual or technical) decisions, please discuss these first in the issue. Otherwise it might happen that you run into the wrong direction and your effort would be wasted. And your help is too important to be wasted.

Of course you can also clone the GitHub repository and work on your own copy.

Finally

When you have completed your work and want it integrated in the main release of Package Drone, you will need to indicate this with a "pull request" (PR).

In order that we can accept your pull request:

• The code has to compile in the current master (unless you are targeting a specific branch)
• You need to have signed the CLA
• The code has to be checked by the Eclipse IP (intellectual property) team

The last step point is not as scary as it sounds. It might cost a bit of time though. The Eclipse IP team will check if the contributed code is conforming to Eclipse's standards. Meaning: that the code is not just copied elsewhere and that you have signed the CLA.

This process can take a few days up to a few weeks, but it is necessary to keep the project out of legal trouble.

A word on dependencies

If there already is a working solution for a problem consider re-using it. So re-use existing functionalities from Package Drone's dependencies (like Google Guava, Apache Codec, …).

However you cannot simply pick a library from the internet and use it in Package Drone. Each dependency (even minor version upgrades) have to approved by the Eclipse IP team and processed by the project. There may be good reasons for adding another dependency, but there is a process behind that task. Simply picking stuff from Maven Central won't work!