How to Help

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

[Edit]Non-Programmers

[Edit]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.

[Edit]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.

[Edit]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.

[Edit]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.

[Edit]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!

[Edit]Programmers

[Edit]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.
  • 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.

[Edit]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 be reviewed, and someone will have to take responsibility for maintaining the code in future releases and responding to bug reports. 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.

[Edit]JUnit tests

JAMWiki integrates JUnit tests using the standard Maven framework. This means that within each Maven project is a src/test folder that contains unit tests. All interested developers are encouraged to create new tests for the JAMWiki code base. 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, helps get new developers familiar with the code, and is something that is greatly appreciated.

To add new JUnit tests

  1. Either create a new test class or modify one of the existing test classes within the src/test folder. An example of the naming convention for JUnit tests is:
    The class for which a test is being written is org.jamwiki.servlets.ServletUtil.
    The test class should be named org.jamwiki.servlets.ServletUtilTest.
  2. The test will now be automatically run during any Maven build, and results will be output to the console. Results will also be available within the project's target/surefire-reports folder.
  3. 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.

To add new Paser JUnit tests

Since wiki syntax parser tests are the most common test cases, special infrastructure has been created for these tests.

  1. Create a new file in the jamwiki-core/src/test/resources/data/topics folder with a name that describes the functionality being tested - for example DefinitionList2
  2. The test file should contain wiki syntax, just as would be entered for a new topic being created on a wiki.
  3. Create a file with the same name as the file created in step 1 and add it to the jamwiki-core/src/test/resources/data/results folder.
  4. The result file must contain the exact HTML output that should be rendered by the parser. Whitespace and newlines must exactly match the parser output, otherwise the unit test will be considered a failure.
  5. The test will now be automatically run during any Maven build, and results will be output to the console. Results will also be available within the project's jamwiki-core/target/surefire-reports folder.
  6. 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.

[Edit]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.db package that extends org.jamwiki.db.AnsiQueryHandler. This class should override any methods in AnsiQueryHandler that need a database-specific implementation.
  3. Create a new class in the org.jamwiki.db package that extends org.jamwiki.db.AnsiDataHandler. This class should override any methods in AnsiDataHandler that need a database-specific implementation.
  4. There are several configuration files that will need to know about any new database code, so search the full codebase for an existing database (example: "db2") and update the code for your database by following existing examples.
  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.

[Edit]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.

[Edit]Maven Enhancements

Currently the JAMWiki Maven build structure is a bit rough. In particular, Maven reports have not worked since JAMWiki was split into sub-projects, there are some ugly hacks to support excluding Java 5 code in some builds, and the POM files could use some cleanup. Anyone with detailed knowledge of Maven who is interested in helping in any of these areas, or who has other ideas on how JAMWiki can make better use of the Maven build structure, is encouraged to help out.

[Edit]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

[Edit]SVN Merging

The Sourceforge Subversion repository is now using the Subversion 1.5 server, which makes merging of branches much easier. Users of the Windows 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. Those using other SVN clients should consult the documentation for that client to understand how best to merge a branch to/from trunk.