Current development on JAMWiki is primarily focused on maintenance rather than new features due to a lack of developer availability. If you are interested in working on JAMWiki please join the jamwiki-devel mailing list.

How to Help

Contributions to JAMWiki are welcome. Specific areas in which contributions are encouraged are listed below. Developers and others wishing to contribute are also encouraged to join the jamwiki-devel mailing list (note: development discussions only).

Contents

Non-Programmers[edit]

Documentation[edit]

Documentation constantly needs updating, re-organization, and additions, so individuals wishing to contribute documentation are highly 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[edit]

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. All translation updates made on jamwiki.org 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 the 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.

Testing[edit]

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 something about JAMWiki does not work for you, a bug report would also be helpful. Simply create an entry in the JIRA bug tracker page that includes:
    • A description of the problem.
    • How to reproduce the problem.
    • Your application server, OS, and database (if any).
    • Any relevant messages from your log files.

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 Latest News 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.

Art, Styles, and UI[edit]

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.

JAMWiki Promotion[edit]

Help promote JAMWiki by adding your site to the list of sites Powered by JAMWiki. This list helps show where JAMWiki is being used and also promotes your site to other JAMWiki users.

Programmers[edit]

How to contribute[edit]

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:

  • Join the jamwiki-devel mailing list.
  • Start a discussion about the feature on the mailing list or on jamwiki.org
  • 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. Development branches are usually cut from trunk, and while branch names are not important most developers use the naming convention "branches/userid", where "userid" is either your Sourceforge ID or JAMWiki login. Changes should only be merged to trunk once they have been reviewed and approved, with the exception of obvious fixes which can be committed to trunk immediately.
  • 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.

There are some common development practices that all code contributions should follow:

  • 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.
  • Do not make single commits 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.
  • Changes that break existing functionality will not be merged with trunk. Existing JAMWiki users expect that functionality will not break between releases.
  • When adding new code, do not duplicate existing functionality. If there is a utility method available that is close to the functionality you require, modify that method to meet your needs rather than creating a second method that varies in only minor ways. There is a high cost to maintaining code, so the more code that can be shared the lower the maintenance costs.

Project Ideas[edit]

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.

JUnit tests[edit]

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 Parser 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.

Adding Database Support[edit]

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.

Packaging JAMWiki for inclusion in Linux Distributions[edit]

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.

A .deb package for Debian/Ubuntu would be high priority as would one suitable for Fedora and other corporate Linux systems.

Packaging JAMWiki for inclusion in one-click installer suites[edit]

Cloud and shared web hosting typically relies on "one-click" installation suites such as bitnami or the control panel software typically implemented on shared hosts.

For LAN or desktop use, the bitnami suite supports DokuWiki and mediawiki installation on top of XAMPP (which already installs Tomcat and configures it). A similar installer for jamwiki that included Java installation would likely be widely used as it would standardize the Java version used by bitnami users.

Semantic features[edit]

The Semantic Bundle software has been updated for Semantic Mediawiki which has had poor support for a few years since its major corporate supporter ceased contributing. The semantic features now constitute a major advantage of using PHP-based mediawiki over Java-based Jamwiki.

Even the simplest implementation of the property notation and category rules of Semantic Mediawiki in jamwiki would blunt this edge considerably and keep those experimenting with semantic web features using jamwiki rather than shifting their mediawiki-format pages to Semantic Mediawiki, as they now can do with assurance of support.

Maven Enhancements[edit]

Currently the JAMWiki Maven build structure is a bit rough. In particular, Maven reports have not worked since JAMWiki was split into sub-projects 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.

Using Subversion[edit]

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

SVN Merging[edit]

The Sourceforge Subversion repository makes merging of branches fairly simple. 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.