Difference between revisions of "Release Procedures"

From Jmol
Jump to navigation Jump to search
(hints on where to find source files (this should have a page of its own, though))
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{Jmol Development Sections}}
 
{{Jmol Development Sections}}
 +
 +
=== 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 [http://www.cs.ubc.ca/~ewout78/SVN.html here], and an on-line book on SVN [http://svnbook.red-bean.com/en/1.1/index.html here] (of the book, the chapter [http://svnbook.red-bean.com/en/1.1/ch03s05.html Basic Work Cycle] gives a good quick start.
  
 
=== Accessing a Release ===
 
=== Accessing a Release ===
  
You can [http://jmol.svn.sourceforge.net/viewvc/jmol/ browse the latest source code online] or anonymously checkout the project contained in the Subversion (SVN) repository.  
+
You can [http://sourceforge.net/p/jmol/code/ browse the latest source code online] or anonymously checkout the project contained in the Subversion (SVN) repository.  
  
To checkout the source code use the following command:
+
To checkout the Jmol source code use the following command:
  
   svn co https://jmol.svn.sourceforge.net/svnroot/jmol/trunk/Jmol
+
   svn co https://svn.code.sf.net/p/jmol/code/trunk/Jmol
  
 
This will check out to the Jmol subdirectory on your system.
 
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:
 
You can update the source code from withing your Jmol sandbox by saying:
 
   
 
   
   svn update  
+
   svn update
  
 
=== Compiling a Release ===
 
=== Compiling a Release ===
  
Compiling can be done via command line by starting [http://ant.apache.org/ Ant] in the top directory, or via an IDE compiler as [[Eclipse]], [http://www.netbeans.org Netbeans], or [http://www.codegear.com/products/jbuilder JBuilder]. The compiled files will be written to the 'build' subdirectory. (Hint: Start looking for the source files for the main parts of the program in the 'src/org/jmol' and 'src/org/openscience' subdirectories)
+
Compiling can be done via command line by starting [http://ant.apache.org/ Ant] in the top directory, or via an IDE compiler as [[Eclipse]], [http://www.netbeans.org Netbeans], or [http://www.codegear.com/products/jbuilder 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 {{File|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 :
 +
 
 +
<pre>
 +
  version=11.3.8_dev
 +
 
 +
  # --------------------------------------------------------------------
 +
</pre>
 +
 
 +
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 {{File|Jmol.properties file}} should for example start with:
 +
 
 +
<pre>
 +
  version=11.3.8_dev
 +
 
 +
  # bug fix: "axes scale ..." did not work for the "axes unitcell" option
 +
 
 +
  # --------------------------------------------------------------------
 +
</pre>
 +
 
 +
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 [http://sourceforge.net/tracker/?group_id=23629&atid=379135 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 [mailto:jmol-users@lists.sourceforge.net 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 [http://svnbook.red-bean.com/en/1.1/ch03s05.html#svn-ch-3-sect-5.4 this reference]
 +
 
 +
For example:
 +
<pre>
 +
~> svn update
 +
C    src/org/jmol/viewer/Jmol.properties
 +
U    src/org/jmol/modelsetbio/NucleicMonomer.java
 +
Updated to revision 8025.
 +
</pre>
 +
 
 +
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:
 +
<pre>
 +
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
 +
 
 +
</pre>
 +
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.
  
=== Release build ===
+
=== Maintainers only: Release build ===
  
 
  svn update
 
  svn update
 
  ant spotless dist
 
  ant spotless dist
 
  ant test
 
  ant test
<i>update version number in build.xml</i>
+
  <i>update version number in org/jmol/viewer/Jmol.properties</i>
  <i>update version number in org/jmol/viewer/JmolConstants.java</i>
 
 
  svn commit -m "prerelease 10.3.1"
 
  svn commit -m "prerelease 10.3.1"
  svn copy <nowiki>https://jmol.svn.sourceforge.net/svnroot/jmol/trunk</nowiki> \
+
  svn copy <nowiki>https://svn.code.sf.net/p/jmol/code/trunk/Jmol</nowiki> \
     <nowiki>https://jmol.svn.sourceforge.net/svnroot/jmol/tags/pre10.3.1</nowiki> -m "prerelease 10.3.1"
+
     <nowiki>https://svn.code.sf.net/p/jmol/tags/pre10.3.1</nowiki> -m "prerelease 10.3.1"
 
  ant spotless dist
 
  ant spotless dist
 
  cd build/dist
 
  cd build/dist
Line 35: Line 172:
 
  cd incoming
 
  cd incoming
 
  mput jmol-10.3.1-binary.*
 
  mput jmol-10.3.1-binary.*
 +
mput jmol-10.3.1-full.*
  
 
If you use another ftp client then login with anonymous/emailaddr
 
If you use another ftp client then login with anonymous/emailaddr
 
and put ftp into 'bin' mode to ensure clean transfer of binary files.
 
and put ftp into 'bin' mode to ensure clean transfer of binary files.
  
=== To release software to sourceforge ===
+
=== Maintainers only: release software to sourceforge ===
  
 
From http://sourceforge.net/projects/jmol :
 
From http://sourceforge.net/projects/jmol :
Line 50: Line 188:
 
** Create Release
 
** Create Release
 
* Refresh your browser  
 
* Refresh your browser  
* Check {{File|jmol-10.3.1-binary.tar.gz}} and {{File|jmol-10.3.1.binary.zip}}
+
* Check {{File|jmol-10.3.1-binary.tar.gz}}, {{File|jmol-10.3.1-binary.zip}} and {{File|jmol-10.3.1-full.tar.gz}}
 
* Add Files and/or Refresh View
 
* Add Files and/or Refresh View
 
* Scroll down to Step 3: Edit files in this release
 
* 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: .gz &rarr; Update/Refresh
* Step 3: Processor: Platform-independent File Type: .zip -> Update/Refresh
+
* Step 3: Processor: Platform-independent File Type: .zip &rarr; Update/Refresh
 +
* Step 3: Processor; Platform-independent File Type: Source .gz &rarr; Update/Refresh
 
* Step 4: Email release notes ... check and send
 
* Step 4: Email release notes ... check and send
 
* At the top of the page click on 'Files'
 
* At the top of the page click on 'Files'
 
* If you want, edit older releases and change them from <tt>Active</tt> to <tt>Hidden</tt>
 
* If you want, edit older releases and change them from <tt>Active</tt> to <tt>Hidden</tt>
  
=== Inform Jmol users ===
+
=== Maintainers only: How to inform Jmol users ===
  
  svn log <nowiki>https://jmol.svn.sourceforge.net/svnroot/jmol/trunk</nowiki> | less
+
  svn log <nowiki>https://svn.code.sf.net/p/jmol/code/trunk/Jmol</nowiki> | less
  
 
* Send out a message to [mailto:jmol-users@lists.sourceforge.net jmol-users@lists.sourceforge.net]
 
* Send out a message to [mailto:jmol-users@lists.sourceforge.net jmol-users@lists.sourceforge.net]

Latest revision as of 00:23, 28 July 2013

Jmol/JSmol Development

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 File icon.gifJmol.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 File icon.gifJmol.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://svn.code.sf.net/p/jmol/code/trunk/Jmol \
   https://svn.code.sf.net/p/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 File icon.gifjmol-10.3.1-binary.tar.gz, File icon.gifjmol-10.3.1-binary.zip and File icon.gifjmol-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://svn.code.sf.net/p/jmol/code/trunk/Jmol | less