Development

To get the official links to Jalview's source, head over to www.jalview.org/development

Here you'll find notes and helpful info about various aspects of Jalview development.

Getting started with Jalview Development

Do register at issues.jalview.org

You need to have a login at http://issues.jalview.org to be able to contribute to jalview.org. Do it now. If you register, you can also make this wiki better!

Checkout Jalview from GIT

git clone https://source.jalview.org/git/jalview.git

You'll probably need to disable SSL certificate checking for this to work, and you'll need your username and password to access the repository. If you just want to check out the source and not commit, then use

git clone http://source.jalview.org/git/jalview.git

Developing Jalview with an IDE

Jalview has a '.project' file for Eclipse and a (potentially out of date*) NetBeans nb-project directory. In principle, all you need to do to work with Jalview's source is to ask your IDE to look for a project inside the directory where you checked out Jalview's source and hit the 'import' button.

* Here at jalview.org, we prefer eclipse. In fact, we really like the Yoxos system at yoxos.eclipsesource.com which automatically downloads and configures eclipse with a set of specific plugins, and even automatically checks out projects in your workspace. If this sounds interesting then try the Jalview Development with Yoxos instructions.

If you'd rather set up Eclipse yourself, then take a look at this a handy guide to setting up Jalview in Eclipse.

Build process for Jalview

Some brief notes about building Jalview can be found in the 'doc' directory in the source. Basically, everything can be accomplished via the ant build script. Type

 ant help

To get a list of the standard targets available.

If you are setting up an IDE to build Jalview, then there are three key issues:

• Jalview compiles into a 'classes' directory at the top level of the source tree. 'ant prepare' will create that directory and copy in any necessary resources needed on the classpath.
  • Make sure your IDE executes the 'prepare' task before it tries to run Jalview's code.
• The JalviewLite applet has a different set of dependencies (appletlib) to the Jalview desktop (lib).

Take a look at the current release schedule for Jalview

The current release schedule lives at http://issues.jalview.org/browse/JAL#selectedTab=com.atlassian.jira.plugin.system.project%3Aroadmap-panel We are always working on at least one Jalview release, and there's always something being developed for a future version.

Decide which branch you want to base your new code on

Always work on new code in a branch forked from the branch where you'd like the code to be incorporated.

That means, if you want to patch a bug in the current release, checkout the current release branch and create a new branch with a name like 'hotfix/JAL-XYZ'. If you want to add a feature to the next release, check out the next release branch, and fork a new branch called 'feature/JAL-XYZ' - where JAL-XYZ is the code for the bug or issue your patch is addressing. If you're working on lots of issues/bugs, then just use something descriptive - but if you are pushing your branch out to the public repository, please make sure we can understand what the branch is about! You might recognise this approach as the GitFlow model of working with repositories. We really like that way of working, but because our codebase has been around for a long time, we don't enforce the 'official' gitflow conventions as used by the gitflow git tools.

Here are the naming conventions for branches in jalview.git:

• The version in the master branch is the one available from the Download/Launch buttons on the website.
  • Do not fork from the master branch. Always fork from the latest Release_X_Y_Z_Branch (see below)
• Release_X_Y_Z_Branch is the latest code for version 'X.Y.Z' of Jalview. We started this convention with Jalview 2, and it will most likely continue into the jalview 3 series (though things are going to get complicated there!).
  • Release branches for the current and the next release should always be available
• develop includes code that will be incorporated into some future version of Jalview.
  • If you want your patch to appear anytime soon, DO NOT START WORKING ON THE DEVELOP BRANCH!

Pick something to work on from issues.jalview.org

Before you start coding, you'll need to decide what to code/write/fix, and most likely, there's already an issue concerning it over at issues.jalview.org, which you can use to title your new branch.

 If it doesn't happen on the bug tracker, then it hasn't happened yet

 No, really. 

If you wan't to start working on Jalview, then pick a bug or new feature to work on, and LET THE OTHER JALVIEW DEVELOPERS KNOW before you start.

• If you have found a bug or have a new feature request - add it
  • this is really easy, and gets you extra points!
• Coordinating with the Jalview Team
  • Commenting on issues - this will cause emails to be sent to the reporter, currently assigned developer, and any people watching.
  • Send an email to jalview-dev at jalview.org if you want to open up more extended discussion about Jalview development.

You can see if someone is already working on an issue because JIRA indicates who the issue is assigned to. The 'Git Commits' tab also shows any commits with messages tagged with the issue number so you can see if any work has already been done. If no one is working on the issue, then:

• Hit 'Assign to Me' to take on an issue. You can't do this if someone is already working on the issue.
• Hit 'Start Progress' button to indicate you are actively working on the issue.

Joining the Jalview community development effort

All Jalview developers are on one or both the Jalview mailing lists. Links for joining these lists are on the jalview community page

Committing to the Jalview's GIT repository

To ensure that your work gets incorporated into the main Jalview version as soon as possible, you should make sure that any patches or commits that you make to Jalview follow some simple guidelines:

Don't make your commit too large

Generally, your commit is too large if you can't come up with a short sentence explaining the where/what/why of the commit (in the context of the JAL-XXXX issue).

• If you have got lots of changes, then use an interactive commit tool to select specific hunks that relate to each other (e.g. applying i18n string extraction to a particular window, and then committing the updated GUI code and the new keys added to the Message bundle).

If you use Eclipse, then you might find it difficult to commit some of the changes in the file (you have to open the Egit compare editor), so I'd recommend you try some of the git GUIs available

• • • Type git gui if you have command line git installed to open GIT's own GUI
    • Download Atlassian SourceTree
      • If you have a Mac, try GitX, which is far simpler and about as good !
    • Try one of the many other graphical GIT clients out there.

Don't commit broken code or part of a patch

Commits should (wherever possible) not introduce compilation errors, and the compiled system should be more or less functional. If you have a series of interdependent commits, then it should be obvious from the commit message (one or more common JAL-xxxx ids, etc).

It is *extremely important* that you get into these habits, because otherwise, it takes us much longer to review your work, and it makes it much harder to identify any new bugs that might arise as a result of your commits..

of course, no one ever commits buggy code, but hibernating bugs are easy to wake ;)