Everyone is welcome to share his/her code with the qooxdoo community. It is an excellent way to give back to this open source project, and a great opportunity to enjoy a collaborative development experience with other qooxdoo contributors.

Thanks a lot for considering any code contributions!

• As a first step send email the project admin at contribute AT qooxdoo DOT org with a short description of your intended contribution. The project admin will get back to you, offer some help and guidance, and ensure that the policies are properly met. Existing committers to qooxdoo-contrib should also contact the project admins before checking in any new contributions.
• We suggest your contribution to be covered by the same licensing as the qooxdoo framework, i.e. a LGPL/EPL dual-license. If you haven’t already done so, please fill out the license agreement and send it back in an email.
• You need to be a SourceForge user for being granted SVN commit rights. If you haven’t got one yet, please register for a new user account and include its name with your contribution request.
• Think of a unique name for your contribution. This ID is used at several places. Please take care not to choose an all to generic name. Usually, the more specific your name is, the better. Please consider using longer names if appropriate, as this often helps in identifying a contribution. If it doesn’t look awkward, please use an uppercase capital.
• The unique namespace of your contribution can be different from the name of your contribution. It has to be all lowercase. Typically it is preferred to use the lowercase version of your contribution’s name. If that appears to be clumsy, you may use a shorter namespace. Remember, that the namespace also needs to be unique among contributions.
• Decide, which email address of yours should for your contribution. It is being used at several places (e.g. Manifest file, bugzilla, etc.). Please use the same email address as this helps with a consistent management.
• Contributions have their own issue tracking in bugzilla. Please register for a regular qooxdoo bugzilla account (if you haven’t got one already).
• Contributions should have at least a single corresponding wiki page, or as many wiki pages as you like. It is managed by the qooxdoo wiki system that you are most likely familiar with already.

People ready to contribute their code will be assigned a unique SVN directory in qooxdoo-contrib and will be granted SVN commit rights for the repository. The contents of the contribution directory is under the responsibility its maintainers, but we ask everyone to comply to the following policies:

• The contribution SHOULD be organized according to the information given here or by using the skeletons provided in qooxdoo-contrib like skeletonWidget.
• The top-level namespace of classes MUST be unique and MUST not use the default qooxdoo namespace qx. Typically, a good namespace would be the contribution name in lowercase letters.
• No code in other contributions SHOULD be touched without the permission of their maintainers.
• The license terms MUST be stated clearly. The code SHOULD either be licensed under the same dual-license as qooxdoo (i.e. LGPL/EPL), or a license compatible to both LGPL and EPL. Such compatible licenses include BSD, MIT or Public Domain. Unfortunately, the Apache License - while debatable - is not compatible. Choosing a license that is not in conflict with qooxdoo’s original dual-license is very important to make it easy to use it with the framework. It also allows for a later integration of a contribution into the qooxdoo framework itself, if that is desirable.

Documenting the policies and procedures may not be complete yet. If you consider adding a new contribution, please contact qooxdoo’s project lead at ecker AT users DOT sourceforge DOT net.

Starting with qooxdoo 0.8.3 it is much easier to setup a new contribution: Just like creating a new regular qooxdoo application, one can now use the tool create-application.py with the appropriate flag -t contribution to create a pre-configured skeleton structure for a contribution.

Please follow those steps:

• Check out the trunk of the qooxdoo-contrib repository. Suppose you placed it as a folder qooxdoo-contrib next to the checkout of the qooxdoo framework or the unzipped qooxdoo SDK.
• Setup file system links from the qooxdoo folder within the qooxdoo-contrib checkout to your local copy of the qooxdoo framework. Please see the README.txt file in the qooxdoo folder just mentioned.
• From within the qooxdoo SDK or checkout, execute the following command to create a new contribution with unique name MyContribution and unique namespace mycontribution:

tool/bin/create-application.py -t contribution -n MyContribution -s mycontribution -o ../qooxdoo-contrib

• Change to the new MyContribution/trunk folder of qooxdoo-contrib and execute ./generate.py x. The generator script should be executed correctly and terminate after printing out the usage information.
• Change to the demo/default folder and execute ./generate.py source. This should generate the source version of the default demo, which can then be opened in your web browser from source/index.html.

This is an outline of the directory structure of a contribution, as it would be created by using create-application.py as mentioned above. Lets continue to suppose the contribution was named MyContribution. Then you get a directory structure like this:

• MyContribution/ Top-level directory of a contribution with a unique name
  • README General description of the contribution. Version-specific README files are available as well (see below)
  • trunk/ The current development version should always be named trunk. Stable versions are usually snapshots of specific trunk revisions and have their own version numbering.
  • 0.1/ Each contribution release is placed into a directory named after the version number. The preferred numbering scheme is using 0.1 increments, i.e. 0.1, 0.2, 0.3 and so on. If required alpha/beta/pre releases should be suffixed by -alpha, -beta or -pre, respectively, e.g. 0.3-alpha.
    • LICENSE License terms of this version. Typically license terms shouldn’t change between releases.(TODO: so why is it then in a versioned subdirectory?!)
    • README Version-specific README file, including deviations from and additions to the top-level README
    • Manifest.js[on] Formal notation of the contribution’s meta data, e.g. authors, license string, version, etc., named “Manifest.js[on]” (depending on the qooxdoo version you support). The format of the file is plain JSON, which is still human-readable while it also allows for processing by the qooxdoo build system. For details about manifest files, see the version-specific documentation (0.7.x) (0.8.x - 1.0.x) .
    • Other files and subdirectories under the version directory (like config.json or source) reflect the usual qooxdoo application structure, which is documented in the manuals (0.7.x) (0.8.x - 1.0.x) .