Development guidelines

Subversion

Installation

There is two eclipse plugins for eclipse, but the recommended one is subversive from polarion which will be the official one for eclipse : http://www.eclipse.org/subversive/

The “ready to use” eclipse archive for 3.3 already includes subversive. But you can always install it manually : Install Subversive.

Cross project atomic commits

Cross project atomic commits are very important to avoid unusable revisions of the subversive repository. Non atomic commits could lead to bad repository update, compilation problems, and components automated tests problems. To use these feature, I strongly recommend to use the svn kit library as svn client in eclipse, you can see why here. Your settings should look like :

:dev:svn_client.png

If you switch from javahl to svnkit, your checkouted projects may be unable to synchronize, and you'll problably be forced to checkout once again. See migration section on this page.

Subversion file automatic properties

File org.talend.developpement/preferences/subversion.config provides a list of properties to set automatically to files when being added to Subversion. For example, it will set many code files to Unix format (ie without carriage return at the end of lines).

If you use Subversion with command line, copy this file as $HOME/.subversion/config.

If you use Subversion through Subversive (1.1.0 or more recent), import this file in Windows>Preferences>Team>SVN/Automatic Properties

Command line use

To be able to use svn in command line while using svn in eclipse, I recommend to make the checkout outside of eclipse

svn co http://talendforge.org/svn/tos

and then import the projects in your workspace “Import > Existing projects into workspace” while not using the option “Copy projects into workspaces”.

Subversion commit logs

  • Must be written in english.
  • A robot automatically adds a note in the bugtracker if the commit log matches the pattern
$g_source_control_regexp = "/\b(?:bug|issue|feature)s?\s*:?[#]{0,1}(\d+)\b/i";

The following examples match

bug 4512 fixed:....
issue:1234 added ...
Features #3456 created

The following examples don't match

features 1234 & 2345 added: ...
#1234 added: ...

A single commit can refer to several issues in the bugtracker, the same note will be added in each issue. In a single commit log, just write something like:

feature 1234 added: ...

bug 4567 fixed: ...
  • Each commit log have a distinct paragraph for each modification done. Two paragraphs are separated with an empty line. Each kind of modification must be easy to understand just by reading the log. Commits can be bug fix, feature add, improvement, something new, deletion or a simple “modification”. Each paragraph must start with this information.
feature 179 added: schema propagation between components
bug 205 fixed: column names are case sensitive in PostgreSQL
Modification: in components tFileInput*, the content of main part was moved
to the end of start part. This makes the behaviour of tFileInput* the same
as tDBInput. In addition, this modification makes possible the use of an
iterate link going out of these components.

New: ability to use "iterate" link type outside of tFileInput* components.

When a commit is a merge from a branch to another, give details about the merge and what was merge (copy log from original commit).

merge -r135:136 from trunk to branch 1.0

Bug 21 fixed: the calculation of first and last row to read was erronous
when footer was defined and not limit. The calculation is now moved to a
dedicated function getFirtAndLastRowNumber in talend::filesOp.

When a commit is a multiple merge, give details about each merge and reuse the original commit log.

merge -c11909 from branch 2.3 to trunk

Bug 3242 fixed: Perl tMysqlBulkExec and tPostgresqlBulkExec now explicitely
declare tMysqlOutput::Mysql (and tPostgresqlOutput::Postgresql) as required
libraries so that they are exported during "export script" operation.

Modification: tMysqlUpdateBulkExec does not need tMysqlOutput::Mysql, the
"use" was removed from generated code.

merge -c11468 from branch 2.3 to trunk

New: 2 Perl TUJs to check tFileInputPositional with basic settings and with
the "trim all columns" option. tFIP_basics logically fail because the unpack
function automatically trim (which is the opposite of what the GUI let the
user think), this will be fixed on trunk when using substr function instead
of unpack.

Migration

In case of:

  • CVS repository to SVN
  • SVN repository location changes
  • Subversive client library changes

Create a patch (Optional)

If you have some work in progress in your workspace which is not ready for commit, you'll need to create a patch.

  1. Select all your projects
  2. Right Click and go to “Team → Create Patch”
  3. Select a location for your patch file
  4. Click “Finish”

Prepare your workspace

You can choose between the following alternatives.

Create a new workspace (Prefered)
  1. Click “File → Switch Workspace”
  2. Enter a location for your new workspace and click ok
Delete all your projects
  1. First make a backup of your workspace !
  2. Verify your backup !
  3. Select all your projects
  4. Right click and go to “Delete”
  5. Choose “Also delete contents in the file system” and click ok

Check out from subversion

  1. Go to “Window → Open Perspective → Other”
  2. Choose “SVN Repository Exploring” and click “Ok”
  3. Create a new Repository Location
  4. Enter “Url” (ask to your svn admin), and “User”
  5. Goto “TRUNK” and Select your projects
  6. Right click and select “Check out”
  7. Return to the “Java Perspective”

Reapply your patch (Optional)

  1. Right click on one of your projects
  2. Go to “Team → Apply patch”
  3. Enter your patch location and click “Finish”

Internationalization

Babili

Known as i18n. Internationalization is the process of designing a software application so that it can be adapted to various languages (Wikipedia).

Babili is the only place where strings are translated.

Only edit messages.properties and plugin.properties files, never edit messages_*.properties and plugin_*.properties files (messages_en.properties or messages_zh.properties for example). Localized messages_*.properties files are exported from Babili and commited into SVN, without taking into account local changes (changes made outside Babili).

messages_*.properties are stored in the *.nl plugins, in the same directory as the messages.properties of the corresponding plugin. For example, org.talend.core.nl/src/main/java/messages_fr.properties contains french strings for org.talend.core/src/main/java/messages.properties.

The key/value is loaded from the messages.properties files. The value initializes the english translation in Babili. The localization team validates the english strings. Once loaded into Babili, it becomes useless to change the values in messages.properties. If you had some new keys, they will be loaded into Babili at next import.

All strings displayed in Talend products must be internationalized, or else it's impossible to translate them. The file http://talendforge.org/trac/tos/browser/trunk/org.talend.developpement/translation/need_i18n_strings.txt lists strings that are not internationalized, so please internationalize them and remove them from the file.

Development advice

Message with variables

Avoid composition of strings. Use variables. For example, instead of replacing

String message = “There are ” + count + ” folders.”

by

String message = Messages.getString(“key1”) + count + Messages.getString(key2)

replace it by

String message = Messages.getString(“key1”, count ) where

key1=There are {0} folders.

Which string to externalize

Externalize all the strings that the user can read

  1. Every string appearing in the UI
  2. Externalize error messages and all messages that have a level of at least INFO (INFO, WARN, ERROR, FATAL).
  3. Do not externalize debug messages.

Code formatting

Format your code easilly

Use talend-code-formatter.xml file in org.talend.developpement\preferences by importing it in eclipse via Window/Preferences/Java/Code Style/Formatter/Import.

Use talend-code-templates.xml file in org.talend.developpement\preferences by importing it in eclipse via Window/Preferences/Java/Code Style/Code Templates/Comments.

We'll active automatic “code format”/“organize imports” on save in java editors. To do this, go in windows/preferences → Java/Editors/Save Actions and check “Format source code” and “Organize imports”.

Check your formatting

Use Talend_Checks.xml file in org.talend.developpement\preferences by importing it in eclipse via Window/Preferences/Checkstyle/New.

Use of task tags

To get the tag in Eclipse : Use talend.epf file in org.talend.developpement\preferences by importing it in eclipse via File/Import/Preferences/Import all.

  • DOC: Indicate a portion of code which has to be commented
  • TSLT: Indicate a variable or a method to translate (All must be in english including remarks).
  • FIXME <user>: For emergency actions
  • PTODO <user>: Personnal ToDo. Must be fixed by the developper (identified by his username). There’re not in the Maven reports.
// PTODO mhelleboid handle zoom and size
  • TODO <user>: This tags is used for Global ToDo. It’s very important. Allow ToDo to appear in Maven reports

NOTE<user> represents the developper username (example:smallet).

WARNING Avoid trigram use complete username.

Team project set checkout

Team project sets are useful when one needs to checkout several projects at once. Eclipse project sets descriptions are stored in ”.psf” files. A first project set has been created for TOS and its description file is stored in org.talend.developpement in Subversion. How to checkout TOS in a few clicks:

  • Do “File > Import”
  • Choose “Team Project Set”
  • load the “TOS-projectSet.psf” file.
  • Click “Finish”.

That's it.

Development configuration files

In order to share development configurations (like the Eclipse launch configurations), store the configuration files in a folder “dev_conf” of the project. The applicative configuration files must not be saved in this folder. Instead they could be saved in a “conf” folder.

New plugin creation

In order for the Talend's release building system to work correctly, you must ensure some points when you create new plugins.

When new eclipse plugins are created, the following steps must be executed:

  1. Add ”.qualifier” to the version of the Manifest.mf file. Example: Replace “1.0.0” by “1.0.0.qualifier” (this is required so that the appropriate release number is added to the plugin during the release building execution).
  2. Add ”.Talend SA.” as the provider's name in the manifest.mf file.
  3. Add a dependency on this plugin in the appropriate feature. One constraint must be respected: the feature in which this plugin is referenced must be on the same SVN repository as the plugin itself.
 
dev/guidelines.txt · Last modified: 2012/01/19 06:01 by ychen
 
 
Recent changes RSS feed Driven by DokuWiki