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 out the {Development:JalviewYoxos Jalview Development with Yoxos instructions}.

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.

• The version in the master branch is the one available from the Download/Launch buttons on the website.
• 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

 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 JALVIEW COORDINATOR KNOW before you start.

• Coordinating with the Jalview coordinator: The easiest way to communicate is to comment on an issue, or request it to be assigned to you. You can see if someone is already working on an issue because JIRA indicates who the issue is assigned to. If you want to on an issue you should hit the 'Assign to Me' button to take the issue on, and when you start working on it, remember to hit the 'Start Progress' button to indicate you are actively working on the issue. Also look at the Git Commits tab to see what has been done on that issue in the past. This tab lists all the commits that have the relevant issue number (JAL-XXXX) in the commit comment field.
• If you have found a bug or have a new feature request - add it
  • this is really easy, and gets you extra points!

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 thejalview 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 ;)