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.

Lets use the SkeletonWidget that comes with qooxdoo-contrib as a blue print for the the proposed directory structure of a contribution:

• SkeletonWidget/ 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.
    • Makefile If the contribution comes with a (demo) application, this Makefile may be required to build the application.
    • Manifest.js Formal notation of the contribution’s meta data, e.g. authors, license. See below for a detailed description.
    • README Version-specific README file, including deviations from and additions to the top-level README
    • backend/ Backend code should go into a separate directory
    • source/ Source directory (organized like a regular qooxdoo skeleton application)
      • index.html
      • class/
        • skeletonwidget/ The top-level namespace needs to be unique among contributions and is set in the Manifest.
          • SimpleButton.js Namespaces should be rather flat. Do not try to replicate the often deep namespaces in the qooxdoo framwork.
          • theme/
            • classic/
              • Appearance.js If the contribution needs enhancements to the default themes, they should be placed in the appropriate sub namespaces, currently .theme.classic or .theme.ext.
            • ext/
      • resource/ Put static resources like CSS files or images needed by the classes into this directory

Each of the top-level directories within a contribution (such as trunk or a numbered release directory like 0.2) must contain a Manifest.js. This file describes the project and contains meta data about the specific version. The format of the file is plain JSON, which is still human-readable while it also allows for processing by the qooxdoo build system.

• name (String, required)
  Name of the contribution. Identical to the top-level directory name.
• summary (String, required)
  Short summary about the project.
• description (String)
  Longer description about the project.
• keywords (String[])
  List of keywords (tagging, categories), to be used for searches.
• homepage (String)
  Contribution homepage.
• authors (Map[], required)
  Array of maps with the following keys:
  • name (String, required)
    Name of the author
  • email (String)
    email address of the author. Please use AT and DOT instead of @ and . as an anti-spam measure.
• license (String, required)
  License (e.g. LGPL/EPL, BSD, ...)
• version (String, required)
  version string of this particular release. Identical to the version directory name, e.g. 0.2 or trunk.
• qooxdoo-versions (String[], required)
  List of qooxdoo versions that this contribution version is supposed to work with.
• namespace (String)
  Top-level namespace of the contribution. Required if the contribution contains JavaScript classes.
• resource-uri-setting (String)
  Name of the setting for the resource URI. By default the name of this setting is a concatination of the top-level namespace and .resourceUri (e.g. progressbar.resourceUri).

{
  "name" : "SkeletonWidget",
  
  "summary" : "A Sample widget.",
  "description": "This widget can be used as a blue print for other contributions",
  "keywords" : ["widget", "skeleton"],
  "homepage" : "http://contrib.qooxdoo.org/project/SkeletonWidget",
  
  "authors" : [
    {
      "name" : "",
      "email" : ""
    }
  ],
  
  "license" : "LGPL/EPL",    
  "version" : "0.1",
  "qooxdoo-versions": ["0.7", "trunk"],
  
  "namespace" : "skeletonwidget",
  "resource-uri-setting" : "skeletonwidget.resourceUri"
}