Contributing to Apache Santuarioâ„¢

Introduction

The Apache Santuarioâ„¢ Project is an Open Source volunteer project released under a very open 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 (money, time, publicity, hardware, software, conference presentations, speeches, etc...).

To begin with, we suggest you to subscribe to the Apache Santuario mailing list (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. Review the todo list, choose a task (or perhaps you have noticed something that needs patching). Make the changes, do the testing, generate a patch, and post to the dev mailing list. (Do not worry - the process is easy and explained below.)

Help Wanted Here

The rest of this document is mainly about contributing new or improved code and/or documentation, but we would also be glad to have extra help in any of the following areas:

Subversion (SVN) Usage Overview

An overview of how to use Subversion to participate in the Apache Santuario 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.

(Further general Subversion usage information is at subversion.tigris.org and your local user documentation.)

Have a look at the Java or C++ installation pages to see how to get a local copy of the source.

Subversion Committer with HTTPS access

After a developer has consistently provided contributions (code, documentation and discussion), then the rest of the dev community may vote to grant this developer commit access to SVN.

You will need secure access to the repository to be able to commit patches. Here are some resources that help to get your machine configured to use the repository via HTTPS.

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 or the bug database.

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 Jira. Santuario uses Jira for issue tracking. To report a issue, or to submit a patch, go here.

Experienced developers use Jira 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 Jira without caring if it is a bug of our package 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.) Do not be impatient - remember that the whole world is busy, not just you. 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 - perhaps it was not clear enough and the readers eyes glazed over.

Contribution Notes and Tips

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