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).
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.
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:
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:
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:
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.
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.
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.
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:
There are some common development practices that all code contributions should follow:
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.
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
src/testfolder. An example of the naming convention for JUnit tests is:
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.
jamwiki-core/src/test/resources/data/topicsfolder with a name that describes the functionality being tested - for example
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:
org.jamwiki.dbpackage that extends
org.jamwiki.db.AnsiQueryHandler. This class should override any methods in
AnsiQueryHandlerthat need a database-specific implementation.
org.jamwiki.dbpackage that extends
org.jamwiki.db.AnsiDataHandler. This class should override any methods in
AnsiDataHandlerthat need a database-specific implementation.
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.
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.
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.
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
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.