Release Procedures

Jmol/JSmol Development

• Getting Involved in J(S)mol evolution
• Release Procedures
• Important! Use the Jmol Coding Style
• Developing J(S)mol with Eclipse
• Internationalisation (status)
• ProgrammeerZomer / SummerOfCode
• MultiUser Jmol
• Developer mailing list (mirror)

What is this?

Several people are working on the Jmol source code at the same time, probably including you! To keep track of the changes and make sure no-one accidentally erases the work done by the other contributors, Jmol uses the subversion (SVN) version control system. These systems are a bit cryptic for the beginning user, therefore an overview of the main procedure is given on this wiki page. General introductions can also be found on the internet, for example a short one here, and an on-line book on SVN here (of the book, the chapter Basic Work Cycle gives a good quick start.

Accessing a Release

You can browse the latest source code online or anonymously checkout the project contained in the Subversion (SVN) repository.

To checkout the Jmol source code use the following command:

 svn co https://svn.code.sf.net/p/jmol/code/trunk/Jmol

This will check out to the Jmol subdirectory on your system.

To checkout the JSmol source code use the following command:

 svn co https://svn.code.sf.net/p/jsmol/code/trunk

Note that to develop JSmol, you need to have both the Jmol and the JSmol projects checked out.

Also associated with Jmol is JSpecView. It is its own project, involving two check-outs:

 svn co https://svn.code.sf.net/p/jspecview/svn/dev2/JSpecView

 svn co https://svn.code.sf.net/p/jspecview/svn/dev2/JSpecViewLib

You can update the source code from withing your Jmol sandbox by saying:

 svn update

Compiling a Release

Compiling can be done via command line by starting Ant in the top directory, or via an IDE compiler as Eclipse, Netbeans, or JBuilder. The compiled files will be written to the 'build' subdirectory.

A common error is:

  JmolSVN/Jmol/build.xml:196: Unable to find a javac compiler;
  com.sun.tools.javac.Main is not on the classpath.
  Perhaps JAVA_HOME does not point to the JDK.
  It is currently set to "/usr/lib/jvm/java-1.6.0-openjdk-1.6.0/jre"

To solve this problem, make sure that the (sun) java jdk is installed, and that JAVA_HOME points to its directory, e.g.:

  export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun-1.5.0/

Add this command to your .bashrc if needed.

Editing a Release

Changes in the Jmol code should follow the Jmol Coding Style.

Hint: Start looking for the source files for the main parts of the program in the 'src/org/jmol' and 'src/org/openscience' subdirectories.

Submitting a bug fix or new feature patch

Before submitting updated code to the jmol team, always do the following:

• Test your code thoroughly, try different systems and 'incorrect' input.
• When the code is working fine, modify the Jmol.properties file in src/org/jmol/viewer. Simply use the same format as the other modifications.

For example, a Jmol.properties file could start with :

  version=11.3.8_dev
  
  # --------------------------------------------------------------------

That means that the next release will probably be 11.3.8 and there has been no modifications yet in Jmol for this new release After your modification, the Jmol.properties file should for example start with:

  version=11.3.8_dev

  # bug fix: "axes scale ..." did not work for the "axes unitcell" option

  # --------------------------------------------------------------------

These lines will then simply be copy / pasted by the maintainers into the change log accessible on sourceforge with the new version, and the maintainers can quickly edit the Jmol.properties file to prepare for the next version.

Now you are ready to submit the changes. For most fixes it will suffice to create a patch file (the file containing the changes compared to a certain revision). Official Jmol maintainers can use the svn commit system. Make sure that you are performing the following commands from the top of the Jmol directory tree.

 svn update
 svn status
 # At this point, if conflicts appeared after svn update, 
 #  solve the conflicts (see section SVN Conflicts below), repeat 'svn status'
 svn diff
 ant spotless dist
 ant test

As soon as svn status does not present a conflict anymore, your code will be ready to submit.

Most likely you will not have a login for the Jmol commit server. The best way to add patches is then by submitting it to the Jmol Patch Tracker on sourceforge. You need a login on sourceforge, which is unproblematic to obtain. You also need to create the patch file, which can be directly created by the svn diff output:

 svn.diff > floating_point_bug.patch

In the case that you do have a login for the Jmol commit server you can use:

 svn commit -m "Fixed: readCoord function used integer instead of floating point "

In all cases it is a good idea to keep the jmol-users@lists.sourceforge.net mailing list informed of the changes you made.

SVN Conflicts

'svn update' will check for changes commited to the server in the time since your last update. Possible output is:

   A  Added
   D  Deleted
   U  Updated
   C  Conflict
   G  Merged

The most problematic message of these ones is probably the 'C' conflict message. For general ways to deal with conflicts, you can check this reference

For example:

~> svn update
C    src/org/jmol/viewer/Jmol.properties
U    src/org/jmol/modelsetbio/NucleicMonomer.java
Updated to revision 8025.

The conflicting files (marked with a C) need to be checked. Note that 'svn update' will give this warning only once, to see if the conflicts have been solved in the mean time, use 'svn status'.

The conflicting file will contain something like:

version=11.3.8_dev

# -----------------------------------------------------------------------------

#version=11.3.7

# bug fix: reading of JVXL files for orbitals loses phase information
# bug fix: ACD/Labs nonstandard cml "builtin" property reader
# bug fix: isosurface interior cavity was not setting meshdata surfaceSet null
<<<<<<< .mine
# bug fix: "axes scale ..." did not work for the "axes unitcell" option

=======
# bug fix: select dna can select rna if chain is mixed hybrid dna+rna

>>>>>>> .r8025

In this case, the line describing the big fix marked as 'mine' need to go up to the 11.3.8_dev part. Also remove the arrows and equal signs. Conflicts within the code will require a lot more attention, so it is smart to update regularly and don't wait very long to commit code that you've finished. After correcting the errors, perform an

 svn diff

to check if there are any conflicts left that didn't get fixed.

Maintainers only: Release build

svn update
ant spotless dist
ant test
update version number in org/jmol/viewer/Jmol.properties
svn commit -m "prerelease 10.3.1"
svn copy https://jmol.svn.sourceforge.net/svnroot/jmol/trunk \
   https://jmol.svn.sourceforge.net/svnroot/jmol/tags/pre10.3.1 -m "prerelease 10.3.1"
ant spotless dist
cd build/dist
ls
lftp upload.sourceforge.net
cd incoming
mput jmol-10.3.1-binary.*
mput jmol-10.3.1-full.*

If you use another ftp client then login with anonymous/emailaddr and put ftp into 'bin' mode to ensure clean transfer of binary files.

Maintainers only: release software to sourceforge

From http://sourceforge.net/projects/jmol :

• Admin
• File Releases
• in File Release Packages:
  • Edit Releases in order to look at previous release name conventions
  • Add Release - prerelease 10.3.1
  • Type in name
  • Create Release
• Refresh your browser
• Check jmol-10.3.1-binary.tar.gz, jmol-10.3.1-binary.zip and jmol-10.3.1-full.tar.gz
• Add Files and/or Refresh View
• Scroll down to Step 3: Edit files in this release
• Step 3: Processor: Platform-independent File Type: .gz → Update/Refresh
• Step 3: Processor: Platform-independent File Type: .zip → Update/Refresh
• Step 3: Processor; Platform-independent File Type: Source .gz → Update/Refresh
• Step 4: Email release notes ... check and send
• At the top of the page click on 'Files'
• If you want, edit older releases and change them from Active to Hidden

Maintainers only: How to inform Jmol users

svn log https://jmol.svn.sourceforge.net/svnroot/jmol/trunk | less

• Send out a message to jmol-users@lists.sourceforge.net

Contributors

Pimpim, NicolasVervelle, Hansonr, Miguel