Dojo is a community effort, and we need your help!

It's easy to get involved and there are lots of ways you can make a difference:

• Helping other users on IRC, the forums or the mailing lists (mostly inactive due to forums coming online)
• Writing documentation (like this manual)
• Filing good bugs (and test cases) to help developers solve issues quickly
• Working on widget visual design and HTML/CSS
• Writing translations for i18n support
• Writing patches to fix bugs
• Submitting code for new features

The Road To Becoming A Committer

Inside the Dojo community, there are two "levels" of participants. The word "contributors" refers to anyone who submits documentation, bug fixes, or even bug reports and test cases. This large group of designers and developers who are using the Toolkit to improve user experience are the lifeblood of the project. You can become a contributor by sending in a Contributors License Agreement and starting to pitch in in any of the ways noted above.

"Committers" are a subset of the contributor community who have been granted the ability to make changes directly to Dojo. Committers can also vote in Toolkit and Foundation matters. With that power comes significant responsibility. Committers are required to act as the front line of defense against IP pollution, follow community development standards, merge or reject patches sent in by contributors, vote, participate in weekly IRC meetings, and work on criticial release issues. Becoming a Dojo committer is considered to be an honor as it means you've impressed a discerning group of hackers with the quality of your contributions and feels that they can get along with you.

So how do you go from "contributor" to "committer"?

The first step is to file a Contributors License Agreement (outlined below). Once it's been received, start contributing! There's no hard-and-fast rule for how many contributions it takes before you are considered for committer status, but in general you'll need to close important bugs, demonstrate that you are willing to participate in the community (mailing lists, IRC, etc.), and show that you respect community norms and standards. Committers make recommendations to the Foundation Board regarding people they think should be considered for commiter status, so working with a committer to assist him/her with issues that are important for an upcoming release is a great way to ensure that your contributions are integrated and that you will be considered for committer status in a timely fashion.

The Contributors License Agreement

Most forms of contribution aside from providing support to other users requires that you sign and submit a Contributors License Agreement (or "CLA" for short) with the Dojo Foundation. All additions to this manual, for instance, require signed CLAs.

There are two versions of the agreement:

1. The Individual CLA
   • use this version if you're working on Dojo in your spare time or can clearly claim ownership of copyright in what you'll be submitting
2. The Corporate CLA
   • have your corporate lawyer review and submit this if your company is going to be contributing to Foundation projects

Summarized, the CLA asserts that when you donate fixes or documentation, you both own the code that you're submitting and that the Dojo Foundation can in turn license that code to other people. While the text on the agreement suggests that you fax it in, you can submit a valid CLA by:

• snail-mail to the address on the form
• fax to the number of the form
• or an email'd digital photograph of the signed document to <carrie at dojotoolkit dot org>

Sending in a CLA is a one-time thing, and once it's done, you're in the clear to start contributing to all Dojo Foundation projects! To be effective, though, you need to know a little bit about how contributors coordinate their work.

Mailing Lists (mostly inactive due to forums coming online)

Originally, most decisions, support, and coordination happened on the project's mailing lists, however, now we are transitioning over to using forums for the majority of our support and collaboration . The dojo-interest mailing list is our most active list, with over a hundred messages sent to subscribers on some days. Everything from how best to theme widgets to complex debugging of applications happens here. There are several web interfaces onto this list, including the searchable gmane archive and the Nabble interface which allows for participation via the web UI.

Project mailing lists are broken up more-or-less by function. The full list:

• dojo-interest
  
  "The big one", this list is ground zero for the Dojo community. While very high volume, it's the best place (aside from this manual) to find answers to your Dojo-related questions. Remember to search the archives, though! With over 15-- subscribers, someone has probably already run into (and solved) the same problem before.
• dojo-accessibility
  
  Developers and users alike use this list to discuss strategies for making Dojo widgets easier to use with assistive technologies such as screen-readers, high-contrast-mode displays, and magnification systems.
• dojo-jobs
  
  JavaScript devleopers are in short supply, and as always, so are great employers. The dojo-jobs mailing list tries to help Dojo-clued employers and job seekers alike find each other. There's no charge to post a resume or job listing.
• dojo-checkins
  
  Notifications of every change to the code of the toolkit are sent to this list along with notifications of changes to bug tickets in the project's bug tracking system.
• dojo-soc
  
  Dojo sponsors students that participate in Google's Summer of Code program. Discussions on this list center around project status updates, how to best tackle problems, and other Summer of Code related matters.
• dojo-contributors
  
  This semi-private mailing list is by invite only, but don't let that scare you from requesting to be on it if you're contributing to the toolkit. Just send mail to "alex at dojotoolkit dot org" explaining why you should be on the list. Some of the best minds in the DHTML world (including all the Dojo committers) are on this list, and discussion tends to be highly-technical. Dojo Foundation votes take place on this list as well, and the archives are public and searchable. While trying to keep the signal/noise ratio high, Dojo is firmly committed to staying a transparent community.

General mailing list ettiquete holds on these lists, but here's the short list of do's and dont's in case your youth wasn't mispent reading mailing list archives like our was:

• DO search the archives and the FAQ for an answer to your question before posting to the list. The odds are much higher that you'll get a response if your message shows that you respect the time of those who can help you with your problem.
• DO assume that the person on the other end of the discussion isn't out to make you feel stupid or hurt your feelings. Things got much more smoothly in a lossy medium like email when everyone assumes that other folks are just trying to help.
• DON'T tell others that they shouldn't be asking a question because you don't think it's Dojo related. If the question involves JavaScript then there is almost always a Dojo solution just a few keystrokes away. Let the community leaders and senior (I use this term to identify time contributed to the community) list members police inappropriate topics.
• DON'T send email in HTML format. It's fine to send both HTML and plain-text versions of the same message, but never send only HTML-formatted mail.
• DON'T post something if you think it will offend the other person. Civility and common decency is expected of all. No exceptions.
• DON'T set "out of the office" responders for mailing list traffic. Leaving your OOTO message enabled is a fast way to get your list subscriptions suspended.

IRC

Many project developers and users can be found in the #dojo channel in irc.freenode.net. Discussions here range from user support to design of new toolkit features. The IRC channel functions kind of like a "real-time dojo-interest list".

As with email, you should google for an answer to your question before asking it in IRC and civility is expected of everyone.

Every Wed at 3pm PST, contributors of every stripe gather in the #dojo-meeting room (also on irc.freenode.net) for the weekly development meeting. Agendas for these meetings are kept in the main project wiki and the log of each week's discussions are uploaded there once the meeting for the folks who couldn't participate in real time.

Bug Tracking

Most project development revolves around "bugs" or "tickets". All bugs that are found are logged in Trac and subsequently assigned to developers and milestones in which they'll be fixed. This process takes a lot of time and work, and generally speaking the quality of the bug report determines how quickly the issue will get corrected. The best bug reports include detailed instructions on how to reproduce the bug, an attachment that shows the code for reproducing the issue, or a link to a URL that demonstrates the problem.

All bug reports need to include the following information:

• Browser type (IE, Firefox, Opera, ...)
• Browser version
• OS and OS Version
• All steps necessaray to reproduce the issue
• An email address of the person filing the bug or a way to get ahold of him/her.

If you think you've found a new bug in the system, we encourage you to file a bug report on it using the following proceedure:

1. Search the bug database to find similar issues that might have already been reported.
2. If you find an existing bug that covers the issue you're experiencing, ensure that it's reported against the right version, assigned to the right module maintainer, and includes sufficient information to quickly diagnose and fix the bug. Add any additional information necessaray to this bug, potentially logging a comment noting your interest in seeing the bug resolved.
3. If no existing bug is found, create a new one that includes all of the information listed above.
4. If the bug is of significant importance to you, place your email in the CC field so that you will receive any updates that are contributed to the ticket. This also provides a way for the developers to contact you if there is a need to get more information regarding the bug.

The better the bug reports, the faster we can fix things, and improving existing bug reports for issues scheduled to be addressed in the next major release is a great way to get involved and speed improvement in the toolkit. And writing good test cases is just a small step away from writing patches to fix the issues.

Contributing Fixes

In many cases, the hard work of fixing bugs is understanding them well enough to determine what the system is doing and what it should be doing. If you've reached this point in the process of filing a bug report, you may find it just as easy to fix the bug as to report it. What then, though? How do you get your fix merged back into the toolkit?

The easiest way to submit patches to the toolkit is to create diffs and attach them to existing bug tickets. This is a straightforward process, but we'll need a "Contributor's License Agreement" (CLA) on file from you. The process for this is outlined above.

Once your CLA has been received, project committers can review and (potentially) merge your changes to fix the bug. To increase the odds that your patch will be merged, remember the following:

• your patch must conform to the project's JavaScript Style Guidelines
• your patch should be created against the latest version of the toolkit, which you can get from a Subversion checkout (TODOC: notes about SVN, anonymous SVN, etc.)
• All changes should be submitted in "unified diff" format
• A test case should accompany any patches in order to verify that the change actually fixes the issue in question

Special Note For Corporate Contributors

Many companies send inquiries about how to "join the Foundation". While The Dojo Foundation does not have a concept of corporate membership the way some other OSS foundations do, it is still possible for companies to get their needs met inside the community processes outlined above. Most companies who are deeply involved in Founation projects attempt either to hire existing committers or encourage one of their existing employees to become committers. For corporate contributors, the steps to getting involved at a level appropriate for moderate to heavy investement in Toolkit technology (e.g., shipping a product with a Dojo-based UI) are:

1. execute a CCLA with the Foundation
2. plan for IP donations and build a process to ensure oversight inside your organization. The Dojo Foundation is not set up to look out for your IP interests, it is designed to shelter users of Foundation projects from liability related to their use of donated IP. Plan accordingly.
3. find some person(s) inside your organization who will become your public face in the Dojo community. Please select this person carefully. They must be patient, be willing to work with a diverse community, and be familiar with general Open Source development tools and practices. Obviously, you may wind up with any number of committers over time, but selecting someone to attempt to hurdle the bar initially and then help others inside your organization has worked well for other firms in the past. Once you let the project lead know who this person is, the project lead often ensures that he or she is on the right mailing lists.
4. donate code or documentation, pending community review, via bug and enhancement tickets. Code donations must meet community standards including adherence to the style guidelines. A good-faith effort to strictly conform to community norms is greatly appreciated and goes a long way toward building a reputation in the community.
5. as your representatives make a difference in the community, impress the project lead with their involvement and technical ability, and show a willingness to "play well with others", they will be considered for committer status through exactly the same process as non-corporate contributors. The amount of time this takes is variable but is generally measured in months. You are advised not to make product planning decisions based on any timeline for "getting a committer".

Employers should note that committers are individuals, and committer status is not tied to an individuals employment situation in any way. Sponsoring a developer's time on Dojo has historically been the largest factor in reducing the time required for that person to be considered for committer status.

Lastly, if your business needs assistance with Dojo but does not want to sponsor an employee to become directly involved with the project, companies like SitePen, the TurboAjax Group, or even individual committers can provide development and support services that may shortcut the time and effort required to both develop high-quality Dojo code and speed its inclusion in the toolkit mainline.