Rob Stryker [
https://community.jboss.org/people/rob.stryker] modified the document:
"Developing for JBoss Tools"
To view the document, visit:
https://community.jboss.org/docs/DOC-21381
--------------------------------------------------------------
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
https://community.jboss.org/docs/DOC-18124 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
(
https://community.jboss.org/docs/DOC-16604). 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
https://community.jboss.org/docs/DOC-15209 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
(/servlet/JiveServlet/downloadImage/102-18462-4-18759/HowWeBuild_Diagram.png) 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
(
https://community.jboss.org/docs/DOC-18462) 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
https://community.jboss.org/docs/DOC-13341 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
(
https://community.jboss.org/docs/DOC-17497) 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
(
https://community.jboss.org/docs/DOC-21382) and Technical Process
(
https://community.jboss.org/docs/DOC-18373) (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
http://wiki.eclipse.org/Evolving_Java-based_APIs_2 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.
--------------------------------------------------------------
Comment by going to Community
[
https://community.jboss.org/docs/DOC-21381]
Create a new document in JBoss Tools Development at Community
[
https://community.jboss.org/choose-container!input.jspa?contentType=102&a...]