JBoss Tools is a large conglomerate of plugins and components from many different locations. This page will help committers and hackers navigate the process of setting up a development environment, contribute patches, and navigate any approval processes required.

Development Environment

The first thing any developers will want to know is How to set up your development environment. This involves choosing which eclipse you'll want to install, your choices of java, subversion, eclipse target platform, which parts of the svn tree to checkout, and how to run tests from inside your IDE.

Building JBoss Tools

Not all contributors will want to go through the trouble, but, if you really want to make sure your changes work the same in PDE's runtime environment (inside eclipse) as they do from a tycho build, which is the build system we use, you'll also want to try to build your project via the command line. You'll be able to set up your first builds by reading How to build JBoss Tools with Maven 3. All committers are expected to build their component locally and verify the tests still pass before committing any major patches.

Sometimes, running your test suite in PDE vs in Tycho (command line build) have different results in the test suite. This is unfortunate, but it *does* happen. If you're getting inconsistant results, and really need to figure out what's going wrong, you'll want to read about Using Eclipse for Remote Debugging Tycho Build.

Submitting / Committing patches

All commits should reference a jira. All committers are required to have a jira target in every svn commit message. This helps keep our history easy to trace back through when searching for regressions. This helps keep us aware of what use cases caused the regression, and what to look out for and re-test when reverting or re-fixing an issue. Without a jira reference, if "fixing" one regression might create a new one, we'll have no way to find out why the change was committed in the first place, or what the change thought it was fixing.

In general, the process for submitting / committing a patch is:

1) Open a jira describing the bug

2) Attach the patch to the jira.

3) If you are a core developer,

      a) simply commit the patch. Otherwise,

      b) assign the issue to the component lead asking for approval and assistence in committing.

4) Resolve the issue as "done". Make sure to target the fix version accurately.

Try to make sure your description, or at least a closing comment, reference exactly how to replicate the issue, so that QE can verify that the issue is fixed. This also helps maintain the integrity of our code.

What happens after a commit?

For those very curious contributors, core developers, or testers, This Image shows what happens in our infrastructure upon a commit. In short, a hudson jobs get kicked off to build the component, and rebuild any components that depend on it, and push all changes to update sites. You can get a good look at what update sites are used and where over at this article. Knowing what update site to use is very useful for anyone using bleeding-edge nightly builds.

Documentation

Committers and component owners are expected to keep their documentation up to date.They will also need to learn how to Build their Documentation.

Other development tasks

Working with branches is also a bit complicated, since our build system may (depending on the flags used) install items into your maven repository. The Working with Branches article will be very helpful here.

There are other more complicated development tasks that require much more approvals than a simple commit. Creating or removing top-level components from our svn tree have processes associated with them (or will soon ). Moving plugins, tests, or features between components also require such approvals.

1) Adding a new top-level component: Approval Process and Technical Process (TODO)

2) Adding a plugin, feature, or test, to a component: Approval Processt and Technical Process (TODO)

3) Deleting a plugin, feature, or test, from a component: Approval Process and Technical Process (TODO)

4) Deleting a top-level component: Approval Proces and Technical Process (TODO)

5) Moving a plugin, feature, or test, from one component to another: Approval Process and Technical Process (TODO)

6) Adding a different component as a dependency to your component.  Approval Process and Technical Process (TODO)

7) Addition of external dependencies requiring an adjustment to target platform: Approval Process and Technical Process (TODO)

Some of these tasks may not seem complicated, but, they still require wide distribution and notification on the proper mailing lists, and in some cases, followup jiras to the build team. While adding a component as a dependency to your plugin might seem simple, it has the potential to cause circular dependencies, or simply cause  extra builds and waste resources. Often, the build team needs to be alerted to these changes to adjust their cascading builds scripts and properly position your jobs where they belong.

Maintenance and Rampdown procedures

Maintenance releases typically contain only bug-fixes, with no additional features. While there is no official process declared yet, in general, maintenance patches require approval from PM or at the very least another committer on the same component. During rampdown for a major release, such as during candidate releases, similar restrictions are in place. Look here for more information in the future.

During maintenance releases, all forms of api breakage are forbidden. While there is often debate as to what exactly constitutes an api breakage, this eclipse document can help identify what constitutes api breakages and what doesn't. One thing to be aware of is that adding a public or protected method or field to any class that may subclassed DOES constitute a breakage. In theory, a subclass may have a method or field of the same name or signature. However the risk for these situations will be evaluated separately and may still be allowed into maintenance if the risk is low.