How to Help

Contributions to JAMWiki are welcome. Specific areas in which contributions are encouraged are listed below.

1 Non-Programmers 1.1 JAMWiki Promotion 1.2 Testing 1.3 Documentation 1.4 Translations 1.5 Art, Styles, and UI 2 Programmers 2.1 How to contribute 2.2 Project Ideas 2.2.1 Adding Database Support 2.2.2 JUnit tests 2.2.3 Packaging JAMWiki for inclusion in Linux Distributions 2.3 Using Subversion 2.3.1 Tortoise SVN Merging 2.3.2 svnmerge

Non-Programmers

JAMWiki Promotion

Help promote JAMWiki by adding your site to the list of sites Powered by JAMWiki. Not only does this list help show where JAMWiki is being used, but it also helps the Google ranking for your site!

Testing

The rapid pace of development, and the huge variety of systems and software, make testers one of the most valuable roles that contributors can play. Bug reports and beta testing are two areas where interested individuals can be of great help to JAMWiki development.

Reports about what doesn't work and also what does work are greatly appreciated:

• If JAMWiki works or does not work for you, a note about what operating system (including version), application server (including version), whether you are using database or file-based persistency, and if you are using a database then the database (including version) you are using would be much appreciated. Please leave this information on the Supported Configurations#Known Working Configurations page. The following text is an example:

  Windows XP / Tomcat 5.5 / Postgres 8.0.  Works with JAMWiki 0.1.1. -- ~~~~
  

• If something about JAMWiki does not work for you, a bug report would also be helpful. Simply leave a note on the Bug Reports page that includes:
  • A description of the problem.
  • How to reproduce the problem.
  • Your application server, OS, and database (if any).

For those willing to test development versions of JAMWiki, the Building from Source page describes how to build the latest development code. Beta releases are also made available during development cycles, and download links are usually posted on the Feedback and StartingPoints pages. Of particular interest is feedback on the installation and upgrade processes during each beta release - reports of successful installs/upgrades are just as helpful as reports of problems.

Documentation

Documentation for JAMWiki is currently very sparse. Individuals wishing to contribute documentation are encouraged to edit any pages within the Category:JAMWiki on jamwiki.org (or to create new pages, as needed) with whatever aspect of JAMWiki needs explanation.

Similarly, if you find something about JAMWiki that is confusing but don't know how to document it, simply request that clarification be added to the documentation - requests can be left on the Feedback page.

Translations

JAMWiki aims to support as many languages as possible, and translations are always appreciated. Individuals who are fluent in English and another language and who want to help translate JAMWiki into that language are most welcome.

Please note that all translators will need to agree to release their translation file under the LGPL license. Translators should also indicate the name that they would like to see appear in the CREDITS file (usually "John Smith (login)" where "login" is your jamwiki.org login).

There are three options for submitting translations:

1. The easiest way to submit translations is to use the Special:Translation tool on jamwiki.org (access restricted). This tool provides a GUI for updating translation values and is the preferred method for translators to submit translations. To request access to this tool, simply leave a note on the Feedback page indicating what language you are interested in translating. Once a file is translated on jamwiki.org it will be added to the Subversion repository for the next release.
2. Uploading translated ApplicationResources.properties file to jamwiki.org. The latest translation files can be downloaded from Subversion repository at Sourceforge. Simply download the latest version (make sure you have the most recent version!), translate the required values, and then upload it to jamwiki.org using the Special:Upload page. If a translation file has not yet been created for your language simply download the ApplicationResources.properties file and then submit a version that is translated into your language.
3. Translations can also be uploaded directly into the Sourceforge Subversion repository. It is preferred that translators use the Special:Translation tool to allow others to easily view your changes, but if you prefer to upload directly to Subversion please leave a note on the Feedback page indicating your Sourceforge login and the language you would like to work on so that you can be set up with Subversion access.

In addition to the ApplicationResources files, translations are also needed for the default JAMWiki topics, such as StartingPoints. These translation files are used to display translated versions of default topics with new installs of JAMWiki - for example, someone installing JAMWiki in Hungarian should see a Hungarian StartingPoints when installation is complete (note that the page will appear in Hungarian to all Wiki visitors after installation is complete, regardless of the visitor's language). There are two ways to submit translations for default topics:

1. Download the latest version of the files from the Subversion repository at Sourceforge and then submit the translated files on jamwiki.org using the Special:Upload page.
2. Directly submit translations into the Sourceforge Subversion repository. For access to Subversion please leave a note on the Feedback page indicating your Sourceforge login and the language you would like to work on so that you can be set up with Subversion access.

Art, Styles, and UI

Want to change the default JAMWiki look & feel? Got an idea for a new logo? Submit a new logo on the JAMWiki Proposed Logos page, or submit a new jamwiki.css file! Have other ideas for making JAMWiki more visually appealing? Suggest something on the Feedback page! All ideas are welcome.

Programmers

How to contribute

For those who see something missing in JAMWiki, or who want to contribute a bugfix, contributions are gladly accepted. Prior to working on a new feature, the following steps should be taken:

• Start a discussion about the feature on the Current Development Status page to make sure no one else is already working on it.
• Read the Coding Style guideline. Any contributions to JAMWiki should conform to these guidelines.
• The Building from Source document contains instructions for downloading the latest JAMWiki source code.
• If you don't have one, create a Sourceforge account and then request that your account be added to the JAMWiki project.
• For new developers, it is preferred that contributions be made to a personal branch in the Subversion repository. Once the changes have been reviewed then they can be merged onto the trunk. Note that the svnmerge tool should be used to keep your branch in sync with the trunk.
• Developers may also wish to subscribe to the jamwiki-commit mailing list to be informed when new commits are made to the Subversion source repository.

When adding code to the source code repository developers should make incremental changes to facilitate code review; it is much easier to understand a series of distinct changes that slowly modify JAMWiki than to review and debug a single change that consists of thousand of lines of code. When committing code to the source code repository be particularly careful not to commit single changes that perform multiple functions. For example, if a change is made that fixes a bug and also adds a code cleanup then the change should be made as two separate commits.

Project Ideas

Often contributors have ideas about a particular feature that they want to add to JAMWiki, and those developers are encouraged to discuss the feature and hopefully to begin writing code. Be aware, however, that features that add significant complexity or that dramatically change existing functionality may not be merged immediately due to the fact that such code will need to maintained indefinitely. In cases where new functionality is not included by default, contributors are encouraged to maintain branches with their feature, and if enough users use that feature the argument for inclusion increases.

Adding Database Support

One area where programmers can help out greatly is in expanding JAMWiki's database support. Currently JAMWiki fully supports Postgres, MySQL (4.x and greater), and several other databases. By default JAMWiki supports ANSI SQL, but databases that are not fully ANSI SQL-compliant may need database-specific JAMWiki code. Contributors interested in adding support for non-standard databases should do the following:

1. Create a new SQL properties file, following the examples currently found in the /WEB-INF/classes/ directory. The new SQL properties file should include only database-specific statements; any of the ANSI SQL statements from the sql.ansi.properties that run properly on your database should NOT be included in the database-specific file.
2. Create a new class in the org.jamwiki.persistency.db package that extends org.jamwiki.persistency.db.DefaultQueryHandler. This class should override any methods in DefaultQueryHandler that need a database-specific implementation.
3. Update the org.jamwiki.persistency.db.DatabaseHandler to add a new "DB_TYPE" constant for your database, and be sure that your new query handler is initialized from the DatabaseHandler constructor.
4. Update the admin.jsp and setup.jsp to include your new DB_TYPE value as a database option.
5. Test, re-test, and test some more.

Once your have a working SQL properties file and a working query handler, feel free to submit it for inclusion in the next JAMWiki release. And of course, if you have any questions or encounter any problems, feel free to post questions on this Wiki.

JUnit tests

As of JAMWiki 0.4.0 a JUnit test framework has been added. JUnit tests can be found in the org.jamwiki.test package. At the present time the test suite is fairly simple, so interested developers are encouraged to create new tests for the JAMWiki code base. Automated tests are particularly needed for the parser code found in the org.jamwiki.parser.jflex package to ensure that parser changes do not cause regressions.

To add new JUnit tests:

1. Either create a new test class or modify one of the existing test classes within the org.jamwiki.test package. An example of the naming convention for JUnit tests is:

   The class for which a test is being written is org.jamwiki.parser.jflex.HtmlTag.

   The test class should be named org.jamwiki.test.parser.jflex.HtmlTagTest.

2. If you created a new test class, add it to the org.jamwiki.test.JAMWikiTestSuite class by modifying that class's suite() method.
3. Run the test using the ant target ant junit.
4. Provided you are willing to release your code under the LGPL, either upload the changes to jamwiki.org and leave a note on the Feedback page requesting it be merged, or else request Subversion access and commit the changes.

Writing unit tests tends to be a boring and thankless job, but having a full suite of tests that cover all functionality is perhaps the best way to ensure quality code.

Packaging JAMWiki for inclusion in Linux Distributions

JAMWiki currently suffers somewhat from the fact that packages aren't available for popular Linux distributions. Those who are familiar with the process for packaging a product for inclusion into a Linux distribution are encouraged to create packages for JAMWiki.

Using Subversion

JAMWiki code is stored in a Subversion repository hosted by Sourceforge. The Subversion project publishes an excellent guide to using Subversion that provides a good overview of version control using Subversion for new developers. Windows users may also want to download Tortoise SVN, which is a Windows Explorer front-end for Subversion that makes usage of Subversion much easier.

The latest JAMWiki code can be retrieved from the Subversion repository using the following command:

svn co https://jamwiki.svn.sourceforge.net/svnroot/jamwiki/wiki/trunk jamwiki

Tortoise SVN Merging

Users of the Tortoise SVN tool can use that program's merge utility for keeping branches in sync with the trunk, and for merging changes to the trunk. See http://tortoisesvn.net/docs/release/TortoiseSVN_en/tsvn-dug-merge.html for information on how to utilize this functionality.

svnmerge

Users of other SVN clients should consider using the svnmerge tool to keep their personal Subversion branch in sync with the trunk. See http://www.orcaware.com/svn/wiki/Svnmerge.py for a description of the svnmerge tool, and links to Windows and UNIX downloads.

To use svnmerge:

1. Download and install the svnmerge tool.
2. Create a new Subversion branch in which you can do your development.
3. Set merge points for your new branch:

   $ cd /home/user/myproject/trunk
   $ svnmerge init /myproject/branches/mybranch
   $ svn commit -m "Adding merge point for branch mybranch"
   $ cd /home/user/myproject/branches/mybranch
   $ svnmerge init /myproject/trunk
   $ svn commit -m "Adding merge point for branch mybranch"
   

Once merge points have been set you can keep your branch in sync with the trunk by using the svnmerge merge command. This command will merge all available revisions from head (specified by svnmerge init) to the current branch. Note that in the following examples commit.txt is a file that should contain an appropriate commit message for the merge:

$ cd /home/user/myproject/branches/mybranch
$ svnmerge merge -f commit.txt

To see what changes are available to be merged without performing a merge, use the svnmerge avail command:

$ cd /home/user/myproject/branches/mybranch
$ svnmerge avail

To merge a specific revision from head (specified by svnmerge init) to the current branch use the following command:

$ cd /home/user/myproject/branches/mybranch
$ svnmerge merge -r 1436 -f commit.txt

To merge a set of revisions from head (specified by svnmerge init) to the current branch use the following command:

$ cd /home/user/myproject/branches/mybranch
$ svnmerge merge -r 1436,1440-1442 -f commit.txt

To merge changes from the branch back to the trunk the process is the same, but the directories are changed:

$ cd /home/user/myproject/trunk
$ svnmerge merge -f commit.txt

Categories: Developer Documentation