View source for JWT DeveloperFAQ

== Overview ==
Here are guidelines and Frequently Asked Questions for JWT developers and contributors.

See also :
* [[JWT_Modifications | JWT Modification Guidelines]] - Information on how parts of the Workflow Editor can be modified / extended
* [[JWT Ramp-Down-Policy]] - all necessary informations to integrate JWT into Eclipse Releases
* [[JWT Automatic Build]] - how build is automated

== Working with the JWT Source Code ==

=== Installing JWT Source Code from SVN ===

For information on how to access the JWT source code, the layout of the SVN repositories and the dependencies of JWT components, please refer to [[JWT_SVN| JWT SVN Information]].
For write access to the SVN you need to replace the anonymous access with your Eclipse committer account data.

=== Internal Layout of the JWT Source Code ===

See [[JWT_SVN#Detailed_Layout_of_the_SVN| JWT SVN Information]]

=== Building, running and debugging the JWT Source Code ===

See [[JWT_SVN]].

== Working with Bugzilla ==
All developments are tracked using the Eclipse Bugzilla, be it a bug patch, a new feature, a user requirement or a build system enhancement.

=== How to get a Bugzilla account ===
Go there to get an Eclipse Bugzilla account : https://bugs.eclipse.org/bugs/createaccount.cgi .

See also the bugzilla documentation at https://bugs.eclipse.org/bugs/docs/html/using.html .

=== How to watch all JWT bugs ===

Log into the eclipse Bugzilla, then in the Bugzilla Preferences page https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email , add the following emails in the "User watching" list at the bottom and save it:

* jwt.we-inbox@eclipse.org ''for the workflow editor''
* jwt.metamodel-inbox@eclipse ''concerning the JWT metamodel''
* jwt.wam-inbox@eclipse.org ''workflow administration and monitoring''
* jwt.desktop-inbox@eclipse.org ''previewing and validating workflows''
* jwt.transformations-inbox@eclipse.org ''transformations from one model to another''
* jwt.runtime-inbox@eclipse.org ''runtime support''
* jwt.releng-inbox@eclipse.org ''for build process related issues and improvements''
* jwt.website-inbox@eclipse.org ''everything related to the website of JWT''

== How to Extend/Modify JWT ==

=== Legal Stuff ===

A comic that explains how to commit code correctly can be found here: [http://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php IP Process in Cartoons].

=== Extending the Workflow Editor ===

The article [[JWT_Extensions| Extending JWT-WE]] contains information on how JWT can be extended by user-defined plugins that provide e.g. external actions or additional views.

=== Modifying the Workflow Editor ===

The article [[JWT_Modifications| Modifying JWT-WE]] provides information on how several recurring tasks (like adding preferences to the preferences menu) can be accomplished. It also lists good practices (API, string externalization...) that MUST be followed if you want your code to be contributed back to JWT.

=== Creating unit tests ===

JWT uses [http://www.junit.org JUnit] to handle unit testing.
The article [[JWT_Automatic_Build]] includes information about how they are automated.

For now, we don't do GUI unit testing, besides having briefly tried [http://eclipse.org/swtbot/ SWTBot]. If you want to, there are [[Automated_Testing|several solutions to Eclipse UI automated testing]], which include [http://www.xored.com/products/q7 Xored Q7] which is demonstrated testing JWT [http://www.youtube.com/watch?v=jtzIF6VX3Fo in this video] (courtesy of Andrey Platov).

== How to nicely fix a bug? ==

In order to provide an increasing quality, here is a suggestion of "how to solve a bug in JWT". These steps are not mandatory steps, however, we really encourage you to follow them, since they guarantee non-regression to JWT.

# If the bug is not reported in bugzilla, report it
# Check out the jwt plugin that contains the bug
# Check out the test plugin for this plugin
# Add a new non-regression test in the test plugin (if possible, if is it really too difficult to write, go ahead) which is named '''testBug[BugId]''' (where bug id is the 6-digits id of the bug you are fixing).
# Add this new test to the AllTests test suite:
## if yoy simply add a test method in an existing TestCase, you won't have anything to do
## If you created a new TestCase class, add this class to the list of TestSuite in AllTests.xml
# Run this test locally (As a "JUnit plug-in test"), ensure it fails, so that you ensure it won't lie to you when it get green.
# Add a patch containing your test on the bug page.
# Get your test committed
## If you are a committer on JWT => Commit it
## If you are not a committer => A committer will commit it to the code, conforming to [[JWT DeveloperFAQ#Legal Stuff]]
# Once committed, your test will be run at each JWT build, you can get test reports for development builds on page [http://download.eclipse.org/technology/jwt/integration-update-site/]
# Make your fix in the "normal" plugin.
# Re-run the test, ensure it is now green.
# Attach your patch to the plugin on the bug page
# Get your contribution committed
## If you are a committer on JWT => Commit it
## If you are not a committer => A committer will commit it to the code, conforming to [[JWT DeveloperFAQ#Legal Stuff]]
# Have a look at next build's report, and ensure that the test case you added succeeded.

== Collaborative Development process ==

The core idea is that what is committed has to fit in JWT on all counts : vision, architecture and legal aspects.

Here is a more detailed outline of how things are typically done :
* first needs and requirements are discussed on the mailing list or on bugzilla(s), as well as whether it fits in the vision
* then a technical solution is proposed, specified and discussed on bugzilla(s), as well as whether it fits in the architecture
* then an implementation is proposed as a patch (or possibly a branch, to avoid if possible) and posted on the bugzilla
* it is reviewed by other committers on the following points : requirements, technical points and whether it fits in JWT's architecture ; and by project leads on whether it also complies to Eclipse and JWT IP and other organisational requirements (CVS layout and naming, dependencies...)
* finally, if it is approved by project leads, it is committed by a committer (the author if he is committer).

Obviously for small things like simple bug patches, a very simple approval is required. If it has only technical (and not vision or architectural) impacts, the approval of the person responsible for the code being patched might be enough.

And once a developer has comitted an initial codebase as specified in a given bugzilla, he can commit incremental improvements to it and only have to mention such improvements in this (open !) bugzilla's comments. More precisely, he doesn't need to write a new bugzilla for each and every commit he does! Once someone's in the process of developing a feature that has already been specified in the bugzilla, he can keep on committing until it's done, at the condition he mentions it on the bugzilla.

Once a new feature has been developed,
* the author must document it in the wiki. If it allows to extend and customize JWT, it must be documented or linked in the dedicated wiki page. As much as possible, a sample and a tutorial should be written on the wiki (how to use it, or how to extend, depending on the case).
* it is reviewed by fellow committers and project leads, who can ask for improvements or refactoring so as it better fits in the JWT architecture (CVS layout etc.), or better doc or samples
* the bugzilla is closed !
* at some point, it will be included in a release (usually the next one), and showcased in the release review slides and in the release news.

== How to prepare a new Release ==

=== Project Management ===
* Maintain [https://projects.eclipse.org/projects/soa.jwt project information] directly using the [https://wiki.eclipse.org/Project_Management_Infrastructure PMI tool].
* In Bugzilla, plan bugs for the release. For this, either use the "version" field as "current development version this bug occurs in" (ex. 1.2 development version of the planned 1.2 release), or [https://dev.eclipse.org/committers/bugs/bugz_manager.php add new release milestones] (at least M6 i.e. API Freeze ; see help at [http://wiki.eclipse.org/Webmaster_FAQ#I_need_to_add.2Fremove.change_a_version.2Fmilestone.2Fcomponent_in_Bugzilla._How_do_I_do_this.3F Eclipse] and [http://www.bugzilla.org/docs/2.16/html/programadmin.html bugzilla]) and make bugs target them
* Update [https://projects.eclipse.org/projects/soa.jwt/releases/1.5.0/plan project plan] directly using the [https://wiki.eclipse.org/Project_Management_Infrastructure PMI tool] & JWT wiki & website CVS with appropriate release themes,
* as well as with committed & proposed bugs, specifying them by version they occur in or (better) target milestones (using ex. [https://bugs.eclipse.org/bugs/buglist.cgi?field0-0-0=target_milestone;classification=SOA;query_format=advanced;type0-0-0=regexp;value0-0-0=^1.2.*%24;product=JWT regular expressions])
* New and Noteworthy :
** Detail (using screenshots) new features and improvements in a pretty manner in a [[JWT_NewNoteworthy_x_y]] wiki page. See previous examples : [[JWT_NewNoteworthy_1_4]], [[JWT_NewNoteworthy_1_3]], [[JWT_NewNoteworthy_1_2]], [[JWT_NewNoteworthy_0_6]], [[JWT_NewNoteworthy_0_7]] (add missing olders ones if any).
** link it in releng/jwt-feature-branding/intro/overviewExtensionContent.xml in SVN,
** resume it and link it on [[JWT_Downloads#Releases]] in wiki & website (see below), where you'll also update all future releases.

=== Legal Process ===

* The legal documentation is one of the most important things at the Eclipse Foundation. If you are not familiar with it, read the [http://www.eclipse.org/legal/guidetolegaldoc.php Guide] first.
* Make sure CQs have been approved for all components on the CVS which should be released ([http://www.eclipse.org/projects/ip_log.php?projectid=technology.jwt IP Log]). This may take a while, so submit them early.
* Submit [http://www.eclipse.org/projects/ip_log.php?projectid=technology.jwt IP Log] using the "submit" button to have them approved for the IP team.
* Prepare review material :
** edit [https://projects.eclipse.org/projects/soa.jwt/releases/1.4.0/review review information] directly using the [https://wiki.eclipse.org/Project_Management_Infrastructure PMI tool]
** reuse as much as possible the review material of the [http://wiki.eclipse.org/JWT_Downloads#Releases last versions] such as [https://projects.eclipse.org/projects/soa.jwt/releases/1.4.0 JWT 1.4.0]
** (a bugzilla report can be generated using [https://bugs.eclipse.org/bugs/report.cgi https://bugs.eclipse.org/bugs/report.cgi])
** About what else to put in, have a look at the [http://wiki.eclipse.org/Development_Resources/HOWTO/Release_Reviews specification] first, as well as these examples : [https://projects.eclipse.org/projects/soa.stardust/releases/2.0/review Stardust 2.0], [https://projects.eclipse.org/projects/soa.stardust/releases/1.0/plan Stardust 1.0], [https://projects.eclipse.org/projects/technology.recommenders/releases/2.1.0/review Code Recommenders 2.1.0], [https://www.eclipse.org/sapphire/releases/8/review.php Sapphire], [https://projects.eclipse.org/projects/technology.xwt/releases/1.0.0/review XWT 1.0], [https://projects.eclipse.org/projects/modeling.emf.diffmerge/releases/0.3.0/review EMF DiffMerge 0.3.0].
* Ask the PMC for approval of the release & slides : provide link to slides & ask PMC members for their +1 at [mailto:soa-pmc@eclipse.org Eclipse SOA PMC mailing list email] ([http://dev.eclipse.org/mhonarc/lists/soa-pmc/ SOA PMC Mailing List Archive])
* Ask for release review at [mailto:emo@eclipse.org EMO], which requires :
** Reviewed / approved IP Log,
** said review material
** said PMC approval (forward PM answer emails)

=== Releasing JWT and the corresponding plugins (e.g. the Workflow Editor) ===

Merely trigger the right automated build in [JWT HIPP https://wiki.eclipse.org/JWT_Automatic_Build#HIPP_builds_.26_Simultaneous_Release], for a mere integration build or to promote it also to Eclipse Simultaneous Release.

----

'''What follows has been OBSOLETED by the automated build'''

==== 1. Preparing ====

* Make sure the ''copyright/year information in the Java headers'' is up to date
* ''Take care of Babel stuff:'' go [http://babel.eclipse.org/babel/map_files.php here] and set the update site URL for the new version. The new version should appear in the [http://babel.eclipse.org/babel/translate.php translator interface] a day or two later.
* ''tutorial_url'' and ''tutorial_path'' must be updated in the ''plugin*.properties''
* ''Remove unneccessary plugin dependencies'' using the ''Plugin.xml''-editor
* Make sure the ''description of the JWT extension points'' is up to date
*'' Close finished Bugzilla tasks'' and ''move open ones'' to the next release (create bugzilla version tag for the next release if not already present - this can be done in the [https://dev.eclipse.org/portal/myfoundation/portal/portal.php portal] in the tools for all committers)
* The remaining open bugzilla bugs can be seen [https://bugs.eclipse.org/bugs/report.cgi?x_axis_field=version&y_axis_field=component&z_axis_field=&query_format=report-table&short_desc_type=allwordssubstr&short_desc=&classification=Technology&product=JWT&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&format=table&action=wrap&field0-0-0=noop&type0-0-0=noop&value0-0-0= here].
* ''Update the internal documentation'' in all plugins such as the JWT-WE (e.g. README, abouttext.txt, about.html, the package.html files in each Java package...)
* Make sure the ''internal version of the plugins'' is set to the new release version
* The ''converter'' must be updated to the newest file format
* Ensure that all ''keybindings for Eclipse commands'' (menu/toolbar) are set correctly
* Make sure the ''licence information'' is valid (notice.html)
* Also the [http://wiki.eclipse.org/Development_Conventions_and_Guidelines development conventions and guidelines] should be followed. Take care of that.
* Run all existing tests (for transformations, workflow editor, etc.)
* Update the release notes

==== 2. Generating Packages ==== 

* Generate new ''Javadocs'' for each component to be released
* Generate a release package and a source package for ''JWT and corresponding plugins''
* Maybe create several packages for different purposes (more or less transformations, etc.)
* Update the ''example processes'' of the workflow editor and create a ZIP archive
* ''[http://wiki.eclipse.org/Modeling_Project_Releng/Building/Signing_And_Packing Sign] all packages''
* Please consider the [http://wiki.eclipse.org/JWT_Automatic_Build Automatic build] information provided

==== 3. Deploying ==== 

* ''Tag the release state'' of the Plugins on the CVS as a new version (e.g. v070)
* ''Archive old release'' (move files to "archive.eclipse.org") and ''upload new release packages'' to the download server "download.eclipse.org" (in a new directory with subdirectories for plugins and documentation)
* ''Update the links'' of archived and new downloads on the wiki download page ([[JWT_Downloads| Downloads]]) and related Wiki pages
* ''Update the Eclipse JWT page'' (add an entry to the news section, adapt direct download link for the Workflow Editor and direct download link for documentation, update project pages, ...)
* Adapt the feature in the ''JWT Eclipse Update Site'' for automatic download
* Change the information in the portal about the successfull release and schedule resp. refine the date for the next release
* ''Notify Mailing List and partners''

----

=== Releasing the AgilPro LiMo/Simulator ===

* update release notes
* update tutorial
* update javadoc
* update howtos
* update install informations
* valid licence in installer?
* valid update splashscreen?
* copy emf model to simulator
* convert sample processes 
* test installer for all operating system versions
* SVN: branch, javadocs
* CVS: tag version
* mylyn: close finished bugs, move open ones to next release

==== Preparing ====

==== Generating Packages ====


==== Signing the Packages ====

1. Using your favourite SSH application (such as Putty), log in to build.eclipse.org using your CVS committer credentials.

2. Move or copy the files to be signed to the Downloads Staging area.
You cannot sign files anywhere else. The Staging Area is at /opt/public/download-staging.priv/, and it is structured like the downloads area.  If you don't have a staging directory, or if you cannot access it, please contact webmaster.

3. Use the 'sign' command, as such:
sign <file> <mail|nomail> [outputDir]

where file is the name of the ZIP or JAR file you want signed.  Because signing is computationally intensive work, wildcards are not supported.

mail|nomail will allow you to receive an e-mail notice that signing is
completed.

outputDir is optional: if specified, signed files will be placed in this directory.  If omitted, the original file will be overwritten with the signed one.

4. When signing is complete, you can verify the signed JAR file with the following command (to verify ZIP files, unzip them first, then verify the JARs inside):

jarsigner -verify <file>

5. Move the signed files back to the downloads area, and delete any other files in the Staging Area.

==== Deploying ====

== Eclipse Maintenance Stuff ==

=== Putting Files on the Download Server ===

* Old files should be moved to ''archive.eclipse.org'':
** ssh yourcommitterid@dev.eclipse.org
** mv ~/downloads/your/project/oldrelease/ /home/data/httpd/archive.eclipse.org/your/project/oldrelease/
* Connect to ''download1.eclipse.org'' using SCP/SFTP and upload the new files
* Update the JWT Download Site
* Update the main JWT site (news area, download area)

=== Updating the Wiki pages ===

Several wiki pages are speaking about the latest version.

All releases with their review slides are normally described [http://wiki.eclipse.org/JWT_Downloads#Releases here].

* Add new overview & detail sections in the [[JWT_Downloads downloads#Releases]] area where the new version is described. Patch older ones if required.
* In the same page, change [[JWT_Downloads#Current_Release]] and if required [[JWT_Downloads#Requirements]]
* The wiki page [http://wiki.eclipse.org/JWT_Release_Engineering Release Engineering] also speaks about releases and should be updated, too.

=== Updating the Web Site ===
Use Git to check out the [http://git.eclipse.org/c/www.eclipse.org/jwt.git Git repository of the JWT web site] whose Git URL is : '''ssh://yourcommitterlogin@git.eclipse.org/gitroot/www.eclipse.org/jwt.git''' (as said at [https://bugs.eclipse.org/bugs/show_bug.cgi?id=412184 #412184]). See more information about working with Eclipse Git repositories at [[Git]].
* using Git command line client : git clone ssh://yourcommitterlogin@git.eclipse.org/gitroot/www.eclipse.org/jwt.git
* you can also use the [http://www.eclipse.org/egit/ EGit Eclipse plugin]

Update at least pages :
* (yearly) release news on the right of http://www.eclipse.org/jwt/ : (before, add / update older news if required) on release day, add a news item inspired by past one & wiki "release" blurb
* eclipse version requirement, current & upcoming on the right of http://www.eclipse.org/jwt/download.php : using info taken from [[JWT_Downloads#Requirements]] & [[JWT_Downloads#Releases]]..

NB. if your really want to preview our changes before committing and pushing them to the eclipse.org server, see [[Configuring Eclipse to Edit your eclipse.org Website]]

Commit and push your changes to the eclipse.org server.
* using Git command line client :
<nowiki>
# get the latest changes before committing if any
git pull
# add all changes to be committed
git add .
# commit them locally
git commit
# push locally committed changes to the server
git push
</nowiki>

See more information about working with git at https://github.com/easysoa/EasySOA/wiki/Git-Quickstart .

Finally, check your work at http://www.eclipse.org/jwt !

== Adapting the Eclipse Update Site ==

In order to adapt the Eclipse update site you need to create a feature first. This shall include all plugins that will be deployed.

=== Creating the feature ===

You'll first need to create a new feature project via the "File -> New -> Other..." dialog.

[[Image:CreateFeatureProject.PNG]]

Then, open the feature.xml to specify all your requirements. The name of the feature, who the provider is, etc. You should also specify the copyright and licensing information there, add the plugins you want to be part of the feature and then compute the dependencies. Afterwards you can go back to the overview page and go through the steps in the Exporting area.

[[Image:FeatureOverview.PNG]]

First, synchronize your plugins with their versions in the workspace, specify the Build configuration and then Export the feature.

[[Image:ExportFeature.PNG]]

In this dialog you will be asked where to create this new feature. Since we want to create a new update-site it makes sense to select already the path of this update site. You can specify several options there and start the process of signing the JAR (if not happened already) and can then click on Finish.

=== Creating the update-site ===

The feature overview allows you also to create an update site project in the Publishing area. There you can open the update site map (site.xml) and specify the feature as well as system requirements. Finally, build the feature and your update-site will be finished.

[[Image:UpdateSite.PNG]]

Now all there is needed is that you upload your update-site to the Eclipse-server. Probably you'll have a directory structure as the following:

[[Image:DirectoryStructure.PNG]]

= Notify =

== JWT & Eclipse ==
* JWT mailing lists : jwt-dev@eclipse.org
* JWT Website : http://www.eclipse.org/jwt/
* JWT Forum: eclipse.technology.jwt
* friend projects : Eclipse SOA mailing list, SOA IWG

== AgilPro & Augsburg ==
* mailing lists for [https://sourceforge.net/projects/agilpro/ AgilPro] and [http://www.informatik.uni-augsburg.de/en/chairs/swt/ds/projects/semtech/sempro/ SEMPRO]
* As the SEMPRO tools build upon JWT, changes to the codebase has probably also effects on the codebase of SEMPRO. Therefore, communicate the changes to the [mailto:sempro@wiwi.uni-augsburg.de SEMPRO mailing list].
* SourceForge.Net [https://sourceforge.net/projects/agilpro/ AgilPro] Announcement Forum
* SourceForge.Net [http://sourceforge.net/projects/wf-codegen/ Wf-Codegen] Announcement Forum
* News at [http://www.e-mundo.de/agilpro.0.html AgilPro Website]

== OW2 ==
* involved research projects mailing lists :
** rntl-sco-2006@objectweb.org (SCOrWare http://www.scorware.org),
** rntl-esb-2005@objectweb.org (old JOnES mailing list, which bore OW2 PEtALS)
* friend OW2 projects mailing lists : 
** bonita@ow2.org (OW2 Nova Bonita)
** petals-users@ow2.org (OW2 PEtALS)
** frascati@ow2.org (OW2 Frascati)
* [http://wiki.scarbo.ow2.org/xwiki/bin/view/Main/WebHome Scarbo] news

== Open Wide == 
* [http://www.easysoa.org EasySOA] mailing list : easysoa-dev@googlegroups.com

== News sites ==
* InfoQ
* openPR.de

= Automatic build =

[[JWT_Automatic_Build | Automatic build description]]

= See also =

* [http://www.eclipse.org/jwt/ JWT Website]

[[Category:FAQ]]