Committers Guide

This guide summarizes the responsibilities and obligations of committers to the qooxdoo framework. If you have any questions or suggestions, please contact the project lead.

Roles & Responsibilities

Project Lead

Responsible for the core aspects of the project. For instance this includes the roadmap planing, release schedule, development focus, quality assurance, licensing, cooperations. This role also implies to lead and work closely with the core framework team and to approve all the other project roles as described below. The project lead can be consulted for any questions related to the project and acts as a facilitator in resolving technical and non-technical conflicts.

Committers

Full access permissions to the qooxdoo code repository require a strong sense of responsibility. It is crucial to act in a well-considered way to ensure the best overall results in accordance with the fellow developers and the project rules. It is particularly important to contact the respective maintainers early for proposing and discussing any non-trivial changes and taking their decisions seriously. No non-trivial code is to be committed without the explicit consent of the respective maintainer.
List of committers

Framework Maintainers

Among the group of committers designated maintainers are responsible for certain parts of the framework. Becoming a maintainer requires to be able to meet all associated obligations in a steady and timely manner. Typically members of the framework core team will be responsible as framework maintainers. But other committers that meet a maintainer's obligations are welcome to apply for maintainership of framework parts. They will get associated a co-maintainer out of the framework core team, so that a close collaboration along the project's guidelines is guaranteed.
Framework areas and maintainers associated

Contributors

There are many ways to contribute to the project. For instance this could mean improving the wiki-based homepage or promoting the framework in blog posts or articles. With respect to actual coding this usually implies full access rights to the qooxdoo-contrib repository and/or providing significant code patches (typically attached to bug reports) to the framework. Every committer and contributor is welcome to add himself/herself to the corresponding section of the developers document. A paragraph or two about who you are and what your involvement with the project is would be great, as well as providing a picture.
List of contributors to qooxdoo-contrib

Contribution Maintainers

Each contribution in qooxdoo-contrib has to have at least one maintainer. While the guidelines and obligations of framework development often cannot be applied too strictly, they may serve as a sensible orientation to achieve and keep up a high quality. The maintainers of a project within qooxdoo-contrib should be listed in the accompanying Manifest file.

Domain Experts

Technical innovation or consolidation benefits from engaging developers to contribute their sound expertise in specific areas. Developers are asked to step forward and get themselves involved, while committers and maintainers are asked to take into account and review the input of domain experts.

Users

Regular users are welcome to get themselves involved in the project. Its infrastructure allows for easily providing mailing list posts or bug reports. All community members are also asked to support this open source project by letting others know about it, for instance by adding their own application to the list of real-life examples.

Coding

Coding style

In order to have a consistent code base, make sure to adhere to the qooxdoo Coding style (preliminary, in the meantime see the regular framework code for reference).
A consistent coding style across the framework is more important than personal preference.
A built-in code pretty-printer allows to beautify source code: invoking generate.py pretty modifies the code in-place according to its pretty-print options.

File format

All files need to be in UTF-8 character encoding. Make sure your editor does not prepend an Unicode byte-order mark (BOM).
For cleaning-up whitespaces call generate.py fix regularly.

Code validation

Code validation should not yield relevant warnings and errors. Run generate.py lint frequently and double-check all output conscientiously.

Cross-browser

Your code must account for all the different browsers supported. Using variants is a smart solution for code branching and conditional compilation.

Internationalization

All language/locale-specific code needs to fully support Internationalization. For instance use the appropriate methods (this.tr(), etc.) to wrap any text parts that need translation.

Deployment

All code must run in the build version with the regular set of optimizations turned on, see the optimize settings.
Make sure there are no unexpected log messages, particularly in the build version of your code.

Deprecation

All non-experimental features that are to change - particularly their API - for upcoming releases, should be properly deprecated. Most scenarios can be handled by appropriate ways of deprecation. If possible the deprecations should not only display specific warnings at runtime, but also be accompanied by info messages during regular semi-automatic migration of an app.

It is important to mark the deprecations with the version it is introduced. The best way to do that is to use the @deprecated tag and add since x.x where the version is the version the deprecations is introduced.

Add every deprecation you add as note in the bug for removing the deprecations for the current release. You can find the bugs in this bugzilla query.

Testing

A comprehensive infrastructure for setting up and running tests on the framework is being implemented. Permanent goal is that the entire framework code has sufficient test coverage.

In particular newly introduced code should come with appropriate unit tests. A goal for new contributions as well as existing critical parts of the framework is to have each method being called at least once when running the associated unit tests.

Also when fixing a defect in the framework, accompanying unit test cases that cover the entire issue are requested. This usually means only a minimum of additional work, as the reported problem as well as the code needed to be understood thoroughly in the first place.

Besides unit testing there is another very helpful quality measure to consider: functional testing. Building upon the qooxdoo-specific Simulator project allows to conduct automated user tests in a remotely controlled browser. Any significant visual portions of web applications benefit from being covered by such simulation tests.

Take this additional work seriously, it helps ensuring a minimum level of software quality right from the start. Only when trying to cover new additions with appropriate tests it may be feasible to reach full test coverage of the framework later.

Documentation

A permanent goal is to have a fully documented framework. In order to achieve (and maintain) this, great care has to be taken for all kind of documentation formats: inline code comments, API docs and wiki documentation.

The API Viewer marks all missing documentation. While it is recommended to address missing API docs as early as possible, it is required to complete any missing docs before an actual qooxdoo release.

Experimental contributions are allowed to only partly be documented. They need to be clearly marked as "experimental" (typically in the top-level class documentation or by an @experimental tag in the respective API docs of methods, etc.).

As a kind of "documentation" any significant framework features should also be showcased in the demo browser. Sample applications should target regular qooxdoo users. Rather developer focused samples may go into the test section of the demo browser, but real (unit) tests within Test Runner are clearly preferred.

Bugs

Follow task-oriented development. Any significant (proposed) code change (e.g. API modifications) requires an accompanying issue report. Within the issue tracking system all relevant info (e.g. pros/cons of a proposed solution, additional references) should be collected and evaluated.

Any new as well as existing bugs are subject to a bug triage process. This is collaboratively conducted by the project lead and the maintainers on a regular basis. Please see the documentation of the bug handling process.

Also see the general info of how-to submit bug reports.

Remind yourself to include additional unit tests for the defects reported, especially while fixing an issue. A thorough test coverage helps in finding any related bugs, and ensures that a similar defect is detected immediately in later development.

When fixing an issue, make sure you apply it to all corresponding branches, if that is feasible and without major risk. For instance, a bug fix in trunk (towards the next minor release) should also go into the accompanying branch (towards the next patch release). The target milestone of the bug report should then point to the future patch release, future minor release otherwise.

Please include the revision of the final commit that fixed the issue with your comments of the bug report.

Commits

Comprehensible SVN commit comments are key when maintaining and advancing the qooxdoo code base.

Since you should have a corresponding bug report for all relevant (i.e. non-trivial) issues, always prepend your commit messages with a unified tag in the form of [BUG #1234] .

Legal

All licensing issues are extremely important and should be taken seriously. In doubt you should contact the project lead at license AT qooxdoo DOT org to clarify all potential issues.

All code contributed to the framework must be governed by qooxdoo's dual license LGPL/EPL or by compatible licenses (typically BSD, MIT, Public Domain, etc.). This is particularly important for 3rd party code, whose relevant legal information is clearly to be included at the appropriate places (typically the class header and/or separate license files): i.e. copyright, authors, hyperlinks, license.

Speaking of third-party components: besides a proper attribution in the file headers, etc., please also add information about new external code to a dedicated manual page.

If you plan to apply for commit rights or you like to contribute a significant amount of code (e.g. providing a larger patch), please fill out and send back the personal license agreement. This covers all your contributions that are done on a private basis. When contributing to qooxdoo on behalf of an employer, there is an additional form to fill out and send back.

The project merely provides an infrastructure for contributions, e.g. code repositories or issue trackers. The providers of the infrastructure cannot be made responsible for any violations of licensing terms introduced by user contributed contents. It is in the responsibility of the contributor to adhere to the licensing terms and ensure proper attribution of contributed code or resources.

Schedules

You are requested to adhere to the release plan, see Roadmap. Make sure your code meets the requirements detailed in this document - well-ahead of the actual release date, so that it can properly be tested and reviewed.

See and follow the documented process of release handling.

The devel versions of the online demos are to be updated on a regular basis. Please make sure your code is ready for publication each Friday at 12 p.m. UTC+1. The SVN trunk should be as stable as reasonable at that time. Avoid committing large amounts of code or critical code close to that specific time.

A weekly status blog post ("The week in qooxdoo") helps to regularly inform the qooxdoo community about relevant activities in or around the framework. Framework developers are requested to provide written input each Friday before 2 p.m. UTC+1.