Introduction

This section is for SyMBA developers only: that is, those who are identified on the SourceForge project site as developers or administrators. It offers guidelines in modifying and documenting this STK. You will only be able to modify the website or the code in Subversion if you are a SyMBA developer.

What to include in new Java Classes

If you're contributing new Java classes to the STK, please ensure that you have put in useful javadoc for all methods. If you've created a new package or sub-project, you'll also need to check the top-level pom.xml in the reporting element, and ensure that your source code will get picked up by the javadoc plugin when the mvn site:site command is run.

Also, please copy the LGPL license section from one of the existing Java classes and include it in your file.

Subversion Best-Practices

You can commit changes if one of the SyMBA SourceForge administrators adds you as a SyMBA developer. You will need to contact symba-devel@lists.sourceforge.net if you wish to be added.

  • Run "svn update" Every time you start a programming session with the STK, and also just prior to running "svn commit". This will ensure that you resolve any potential conflicts prior to committing changes.

  • Please only commit when you have a working STK: do not commit code that will break the build. We need to ensure that anyone who checks out our STK from the trunk/ can at least build the project, even if the trunk is in a snapshot state (which it will normally be in).

  • Each time we create a point or full release, it will be tagged and marked in the tags/ subdirectory of the project. This means that users can always choose to stay with a particular release. If we need to bug-fix a particular release separately from what we're already building in the trunk, then we can create a branch for that release in the branches/ subdirectory and work from there. The tags/ subdirectory is never to be committed to, as that would be against Subversion best-practices.

More information on Subversion can be found in its Manual .

Beyond Javadoc: Documenting Your Work

If any of the changes you make change how a user would install or use this STK, please ensure that you update the documentation, which we make available via the website both in html and pdf format. The actual documentation is built using the APT (Almost Plain Text) Format and then generated by maven into other formats.

The APT files are made into a book using the doxia maven plugin - this is a plugin that, in a more generic usage, also builds the maven site documentation when you run the command mvn site:site . The benefit of using the Doxia book plugin is that it can create the book in multiple versions: currently we build the book in xdoc format, which is used by the mvn site:site command, and in pdf, which is manually copied to the FuGE website for download and offline use. Please see the Doxia Plugin Manual and information on writing in APT format .

You build the new version of the book by going into the books/ sub-directory and running the book-generation command:

   cd symba-books/
   mvn doxia:render-books

This builds the book in the symba-books/target/generated-site directory.

Re-Building the SyMBA Website

When you are ready to re-build the entire website, go into the top-level directory and generate the site docs in each of the sub-projects:

   mvn site:site

This actually builds all of the html files. However, they are still in their individual sub-directory's target/site directory. To put them all together and copy them to the FuGE website, you need to use the mvn site:deploy command. However, to prevent accidental copying, the shell.sf.net site element is commented out. Please ensure this remains the case when you are committing changes to SVN.

Also edit your $M2_HOME/settings.xml file by adding the following:

 <server>
 <id>shell.sf.net</id>
 <username>your sf username</username>
 <password>your sf password</password>
 </server>

mvn site:deploy JUST copies the already-generated site docs. If you make a change to any of the APT files, you must run mvn site:site FIRST, to re-generate the site docs, THEN mvn site:deploy to copy them to the final location described in the distributionManagement element of the pom.xml

It is a good idea to test the maven-generated site before publishing to the SyMBA website. Change the url element of the local-test site element below to local directory that is right for you, then deploy locally:

   mvn site:deploy

and check the resulting site. If all looks OK, comment-out the local-test site element and un-comment the shell.sf.net site element. Only developers with write-access to the shell.sf.net server and the symba group area will be able to perform this goal. Run the deploy command again to copy to the real SourceForge webserver:

   mvn site:deploy

The only problem with the site deployment at the moment is that it doesn't copy the non-html books properly. This means that the pdf version of the installation instructions doesn't get put on the server. So, as a final step, you need to scp the pdf manually:

    scp books/target/generated-site/pdf/symba/installation.pdf  your-username@shell.sf.net:/home/groups/s/sy/symba/htdocs/
    scp books/target/generated-site/pdf/symba/general-information.pdf  your-username@shell.sf.net:/home/groups/s/sy/symba/htdocs/
    scp books/target/generated-site/pdf/symba/deviations-from-fuge.pdf  your-username@shell.sf.net:/home/groups/s/sy/symba/htdocs/

Remember, you can only run site:deploy successfully if you are down as a SyMBA developer on the SF site.