License     Codehaus     OpenEJB     OpenJMS     OpenORB     Tyrex     
 

Main
  Home
  About
  Features
  Download
  Maven 2 support
  API
  DTD & Schemas
  Recent changes
  RSS news feed

Development/Support
  Mailing Lists
  SVN/JIRA
  Contributing
  Support
  Prof. services

Related projects
  Spring ORM support
  Spring XML factories

XML
  Using XML
  XML Mapping
  XML FAQ
  XML HOW-TOs
  Custom Handlers
  Best practice

XML Code Generator
  Code Generator
  Properties
  Custom bindings
  Ant task
  Schema Support
  Example

JDO
  Introduction
  Using JDO
  JDO Config
  Types
  JDO Mapping
  JDO FAQ
  JDO Examples
  JDO HOW-TOs
  Other Features
  JDO sample JAR

Advanced JDO
  Caching
  OQL
  Trans. & Locks
  Design
  KeyGen
  Long Trans.
  Nested Attrs.
  Pooling Examples
  LOBs
  Best practice

More
  Presentations
  The Examples
  3rd Party Tools
  JDO Tests
  XML Tests
  Configuration
  Tips & Tricks
  Full JavaDoc
  CastorWiki
 
 

About
  License
  Contributors
  Marketplace
  Status, Todo
  Changelog
  Library
  Contact
  Project Name

  



Contributing to Castor

Documentation Author(s):
Werner Guttmann


Introduction
Guidelines For Code Contribution
Guidelines For Committers
Licensing Policy
Building Castor
    Introduction
    Directory Structure


Introduction

The Castor project is an Open Source project hosted at the Codehaus, and it is released under a very open license. This means there are many ways to contribute to the project by e.g. coding, documenting, answering questions on the mailing lists, proposing ideas, reporting bugs, suggesting bug-fixes, etc.

To begin with, we suggest you to subscribe to the Castor mailing lists. Listen-in for a while, to hear how others make contibutions.

You can get your local working copy of the current code base (or any particular release) from the Castor SVN repository. Review the todo list at Jira, choose a task (or perhaps you have noticed something that needs patching). Make the changes, do the testing, generate a patch (if you need then discuss it on the dev mailing list), and add the patch to Jira.

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, as all other committers will sufficient spend time with you trying to assist you with their knowledge.

Guidelines For Code Contribution

All code contributions must be under the license and copyright of the project to which you contribute. By contributing code you agree that we can distribute the contribution under the terms of the license, that it can be distributed without any royalties, copyright, trademark, patent or other legal lock ups. Open source means no discrimination against any group or individual that may wish to use the code.

When making a contribution you are granting us a world wide, royalty free, unlimited in time license to re-distribute the code under the Exolab and/or Apache license. In case you wonder, you remain the original author and copyright holder of the contribution, you just give other people a license to use it as well. Thank you.

It's perfectly ok to put your name and e-mail address in the code.

When sending patches, unified diff files (3 lines before, 3 lines after) work best:

  svn diff <file>

against the up-to-date SVN version, or

  diff -u <file1> <file2>

It is very important for sending test cases along with the patch of a new feature and a bug fix, as a test case will help the committers to assess the validity of the problem in question and your proposed solution. In general, a test case - showing a feature being added or a bug being fixed - proves that the patch plays along nicely with other code and does not introduce any side effects.

Committer are encouraged to commit a patch only if (s)he fully understands the patch. A test case that assists the committer to gain a full understanding as mandated per above statement, as such ensures the committer understands what the patch does and as a result encourages a prompt review and check-in.

Also, a test case is the easiest way to ensure your contribution will not be broken by another patch later. It becomes even more important if your project depends on a feature that you're contributing.

The last requirement for contributing code is to create an issue (providing a full description of the issue/enhancement) and attach your patch (in from of a unified diff) to this issue. Having created such an issue, this allows your request to be fully traceable.

Guidelines For Committers

Familiarize yourself. Take some time to understand the directory structure, build environment, interaction between components, coding and commenting style. Nothing out of the ordinary, but still not all projects are identical.

Before starting to work please advertise. It's pointless to have two people working on the same feature. Send an e-mail to the developer mailing list and announce what and how. If you don't get a reply within a day, you can assume the coast is clear.

Test before you commit. Before committing any changes run a svn update to make sure you have the latest code base. Run the test cases to make sure nothing is broken.

Commit all at once. If the change involves more than a single file, make sure to commit all the changes together. A partially committed SVN tree is not a pretty sight. No lunch breaks, meetings or sleep during commits.

Be ready to receive complaints. Hopefully all works fine, but if changes to break existing code, people will complain. Be ready to answer their e-mails and apply the proper fixes. No going on vacation five minutes after a commit.

Put your name so people know who to credit. (Also who to blame). Initials work just fine, your full name and e-mail address are already on the main page. If you've added a new file, feel free to put your name and e-mail address as the author. If you're fixing a file, put your initials on the comment.

Observe release time. We're going to announce a new release five hours prior to making it. That gives you four hours to commit any changes, make sure nothing breaks. Don't leave the computer before the release is done. If you can't make it, there's alway the next release.

Document what you've done. In-code documentation, SVN commit messages, and the changelog. Major changes should always be recorded in the changelog.

Use the document DTD. When adding new documentation use the document DTD. Specify the proper document URL, properties, body and section. Everything inside the body/header/section is XHTML. That means well formed HTML. If it's not, you won't be able to build the docs.

We don't have a particular style for documentation, and we do appreciate a sense of humor, sarcasm and literary expression. Just don't overdue it, and please, no cliche.

Licensing Policy

We have a simple policy regarding distributable code. Either it's open source and compatible in license, or it's an API that is freely distributable.

BSD-like and MPL-like licenses are compatible and can be mixed in the same code base. Liberal licenses and public domain are also fine.

APIs need not be open source, but they must be freely distributable. As a policy we like to stick with standard APIs and never modify them, so the license has little affect. We do favor public domains APIs like SAX over tightly controlled APIs, and hopefully we can all do something about that.

Pay special attention to pre-release availability and trademark issues. Several committees and companies require proper trademark acknowledgement in the documentation. Some of them are available for distribution only once they have been formally released. This policy applies to all APIs coming from Sun.

Building Castor

Introduction

Castor uses Ant as the build environment. To build Castor from the source run bin/build.sh or bin\build.bat in the Castor root directory with one (or any) of the following targets:

targetsLists the build targets
cleanCleans the build and distribution directories
allCleans and builds all the packages and examples
releaseCleans and builds all the release packages (JAR, source, doc, tarball) in the dist directory
mainBuilds the main packages (including debugging info)
examplesBuilds the example packages (including debugging info)
testsBuilds the test packages (including debugging info)
jarBuilds the binary JAR in the dist directory
docBuilds the documentation
apiBuilds the API JavaDocs
javadocBuilds the full JavaDocs
sourceBuilds the source tarball in the dist directory
tarballBuilds the binary distribution in the dist directory

The tarball will includes the Castor JAR, all dependent library JARs, readme and license files, and all DTDs and XML schemas in the schema directory.

Directory Structure

binScript/batch files required for building Castor, running samples, CTF et alias
src/mainThe source base for all the Castor modules
src/docDocumentation (in XML form)
src/schemaDTD and XML schema for Castor mapping files
src/examplesExamples for the various packages
src/testsTest cases for the various packages
src/etcAdditional files that are not part of the code base
libJARs required to build Castor and distributable JARs
build/classesWhen using Ant the Java classes are build in this directory
build/docWhen using Ant the HTML documentation is build in this directory
build/examplesWhen using the examples are build in this directory
build/testWhen using the test cases are build in this directory
distThe distribution directory
 
   
  
   
 


Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved.
 
Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners.