Contributing to Apache Shiro


The Shiro Project is an Open Source volunteer project released under a very liberal license. This means there are many ways to contribute to the project - either with direct participation (coding, documenting, answering questions, proposing ideas, reporting bugs, suggesting bug-fixes, etc..) or by resource donations (staff time, conference presentations, publicity, software) and even general hardware/money donations via the Apache Software Foundation.

To begin with, we suggest you to subscribe to the Shiro mailing lists (follow the link for information on how to subscribe and to access the mail list archives). Listen-in for a while, to hear how others make contributions.

You can get your local working copy of the latest and greatest code by following the directions in our Download page. Review the To Do list in the issue tracker and then choose a task that interests you. Perhaps you have noticed something that needs patching, or have a new feature to contribute. Make the changes, do the testing, generate a patch, and discuss on the dev mailing list. (Do not worry - the process is easy and explained below.)

Document writers are usually the most wanted people so if you like to help but you're not familiar with the innermost technical details, don't worry: you can still be tremendously helpful!

Help Wanted Here

You can be a huge help by providing extra assistance in any of the following areas:

Procedure for reporting bugs and issues and enhancement suggestions

If you think that you have found a bug or you have a suggestion for improvement, then please discuss it on one of the mailing lists. However, please check our issue tracker first as it may be already reported.

The Apache Shiro Issue Tracker collates our known issues. Obviously not every issue is listed there. Some issues have been discussed on the mailing list but do not yet have an issue recorded.

The Roadmap is the best way to get an overview. The Unscheduled list also needs regular review, and committers will schedule some of those for the next release.

When creating a new issue, please provide a concise Summary Title and a short Description. Add further information as Comments and include links to the mail archives. The normal procedure is to discuss the issue on the mailing list and then add relevant notes to the issue tracker, otherwise it becomes cluttered.

SVN Usage

An overview of how to use Subversion (SVN) to participate in Shiro development. Do not be afraid - you cannot accidently destroy the actual code repository, because you are working with a local copy as an anonymous user. Therefore, you do not have the system permissions to change anything. You can only update your local repository and compare your revisions with the real repository. The Download Shiro page explains how to check-out the code base and build your local copy.

SVN Committers

After a developer has consistently provided contributions (code, documentation and discussion) and demonstrated committment, then the rest of the dev community may vote to grant this developer commit access to the Subversion repository. See the ASF developers resources especially the Source code repositories.

Procedure for Raising Development Issues

There are two methods for discussing development and submitting patches. So that everyone can be productive, it is important to know which method is appropriate for a certain situation and how to go about it without confusion. This section explains when to use the developer mailing list and the issue tracker.

Research your topic thoroughly before beginning to discuss a new development issue. Search and browse through the email archives - your issue may have been discussed before. Prepare your post clearly and concisely.

Most issues will be discovered, resolved, and then patched quickly via the developer mailing list. Larger issues, and ones that are not yet fully understood or are hard to solve, are destined for the issue tracker.

Experienced developers use the issue tracker directly, as they are very sure when they have found a bug and when not. However, less experienced users should first discuss it on the user or developer mailing list (as appropriate). Impatient people always enter everything into the issue tracker without caring if it is a bug of Shiro or their own installation/configuration mistake - please do not do this.

As a rule-of-thumb, discuss an issue on the developers mailing list first to work out any details. After it is confirmed to be worthwhile, and you are clear about it, then submit the bug description or patch via Bug Tracking.

Perhaps you do not get any answer on your first reply, so just post it again until you get one. (But please not every hour - allow a few days for the list to deal with it.) Bear in mind that other countries will have holidays at different times to your country and that they are in different time zones. You might also consider rewriting your initial posting. It may have not been clear to the readers on the mailing list.

How to prepare and contribute patches

If you use the current development version of Shiro via Subversion, then do 'svn update; svn status' to see what files that you have changed. Do 'svn diff > mypatch.txt' to make a patch which includes every change. To make a patch for a specific file, do svn diff src/documentation/content/xdocs/faq.xml > faq.xml.diff. It is better to prepare the patch from the $SHIRO_HOME directory so that it contains a definite path to the document. However, be careful that the patch does not contain other work-in-progress.

For more information about working with SVN, see Version Control with Subversion - the opensource SVN book.

If you use a downloaded released version of Shiro (or don't use SVN), then use the 'diff' command of your operating system: diff -u faq.xml.orig faq.xml > mypatch.txt (better to do that from $SHIRO_HOME directory). If you want to use the most recent version of the documentation then grab its source file directly from the SVN server (and tell us which Revision number you used).

Please send all contributions via our issue tracker. and specify the Forrest version or svn version of the source.

It is always a good idea to check the Shiro issue tracker before diving in.

How to revert changes in SVN

Check out for instructions on how to revert (roll back) changes to svn.

Contribution Notes and Tips

This is a collection of tips for contributing to the project in a manner that is productive for all parties.