Proposed, draft guidelines for "contributing to Drupal"

I'd like to see a fuller treatment of Drupal aims, structure, and process. What are the aims of the Drupal core, how are decisions made, how can new members contribute? This would be valuable to provide a clear frame of reference for Drupal community members. This could go into the Dupal handbook, likely in the "General information about Drupal" and "Developer's guide" sections. In particular, I could see the existing information in the handbook (bug reports, feature suggestions, creating and sending your patches, etc.) reorganized under a general section of "How to contribute". Towards that end, I've drafted the following for discussion and revision.

Please note: I've drafted this writeup from existing sources and my own understanding. In many cases it may not be accurate. It's posted here for review, not to serve directly as a guide!

Please post comments on this forum topic or - if you have appropriate drupal.org permissions - post changes directly to the text. If and when it's ready, it can be incorporated into the handbook.

Thanks, Nedjo Rogers nedjo@gworks.ca.

Drupal is a collaborative, community-driven project. This means that the software and its
supporting features (documentation, the drupal.org website) are collaboratively
produced by users and developers all over the world.

There are several ways to contribute to Drupal:

• Improve or enhance the software
• Provide support and documentation for other users
• Provide financial support to Drupal development.

This section focuses on the first of these three.

Types of Contributions

There are two basic types of contributions you can make to Drupal's code
base: (a) "contributed" modules or themes and (b) contributions to the
drupal "core".

• "Contributions" are the community-produced modules and themes
  available on the Drupal site.  To make a contribution, you need to apply
  for contributor privileges, produce your contribution, and then notify the
  contributions manager to request a review of your work before posting.  As
  long as contributions meet some minimal criteria - they do what they claim to
  and have some demonstrable benefit without unduly replicating already-available
  functionality - they are approved.

  If you have major enhancements you wish to contribute, doing so via a
  contributed module is in many ways the easiest way to begin.  Contributed
  code has a relatively low set of requirements to meet.

• In contrast, changes to the Drupal core are made through a thorough consultative
  process to ensure the overall integrity of the software.

  Changes to the Drupal core are generally of three types:

  • Bug fixes.  These changes respond to identified problems in
    the existing code.
  • New features.  These changes are enhancements on what is
    already available.
  • Code cleanup.  These changes are to improve the quality of the
    code.  This can include bringing code in line with coding standards,
    improving efficiency (e.g., eliminating unneeded database queries), and
    introducing or improving in-line comments.

Aims of Drupal

Mission: Building on and realizing relevant standards and open source technologies,
Drupal supports and enhances the potential of the internet as a medium where
diverse and geographically-separated individuals and groups can come together
and collectively produce and share rich bases of information and expression.

Use Cases and Target Users

Drupal is designed to be flexible and powerful enough to meet a broad range
of web technology needs, from simple informational postings to large
organizational sites and collaborative projects.  This said, there is a
central interest in and focus on communities and collaboration. 
Drupal aims to enable the collaborative production of online information systems
and communities.

Principles

• Collaboration.  Drupal development supports open, collaborative
  information sharing systems and approaches (including systems such as
  community moderation of posts).
• Standards-based.  Drupal supports established and emerging
  standards.  Specific target standards include XHTML and CSS.
• Open source.  Drupal is based on the open source philosophy of collaborative free software
  development.  Drupal is itself open source and builds on and supports
  other open source projects.  Specifically, Drupal is coded in the open
  source scripting language PHP and supports as primary data sources the open
  source database formats MySQL and Postgresql.
• Quality coding.  High quality, elegant, documented code is a
  priority over roughed-in functionality.
• Ease of use.  Drupal aims for a high standard of usability for
  developers, administrators, and users.
• Modular and extensible.  Drupal aims to provide a slim,
  powerful core that can be readily extended through custom modules.
• Low resource demands.  To ensure excellent performance, Drupal puts
  a premium on low-profile coding (for example, minimizing database
  queries).  Drupal should also have minimal, widely-available
  server-side software requirements.  Specifically, Drupal should be
  fully operational on a server with Apache web server, PHP, and either MySQL
  or Postgresql.

Usability Aims

For developers Drupal aims for a development system that is:

• well-tooled with a system of hooks that provide ready means to
  accomplish most foreseeable coding aims that involve interaction with core
  elements

For administrators, Drupal aims to provide solutions that are:

• easy to install and set up so that there is a minimal
  requirement for specific technical expertise
• intuitive and self-explanatory so that administrators can
  easily find the configuration options they need
• highly configurable so that site administrators can present
  just the interface they wish

For users, all elements of the Drupal user interface should be:

• intuitive and self-explanatory so that users with minimal prior experience can
  easily discover, navigate, and use functionality
• uncluttered so that users are not faces with a difficult task
  of sorting the essential from the non-essential

The Revision Process

Changes to the Drupal core are usually made after consideration, planning,
and consultation.  They are also made on a priority basis--fixes come
before additions, and changes for which there is a high demand come before
proposals that have gone relatively unnoticed.  Any potential change has to
be considered not only on its own merits but in relation to the aims and
principles of the project as a whole.

In Drupal as in many other open source projects, it's not unusual for
first-time contributors to feel frustrated that their offerings aren't taken
up.  This frustration is understandable--when you've taken the time to
contribute something, you'd like to see it adopted or at least considered! 
To lessen the potential for frustration, it's worth considering the steps and
processes that go into maintaining the code.

At a minimum, one of the core developers has to review contributed code for
compliance and apply and test the change before considering
"committing" it.  Keep in mind that Drupal developers are
volunteers who have their own coding priorities.  You have only to look at
the dozens of ideas and suggestions posted every week to appreciate that not all
of them can receive full review.

If every suggested enhancement were immediately applied, the Drupal core
would quickly become bloated.  Instead, significant changes typically go
through a reiterative process of discussion, coding, review, and revision. 
A careful review process helps ensure that every change and addition is
contributing in a balanced way to well-designed whole.

If you wish to get directly involved in developing the Drupal core, joining
and following the drupal-dev mailing list is probably a good step.  This
will give you a feel for current areas of discussion and development and can
also be a forum for inquiries and suggestions.

The particular stages that a new feature goes through vary, but a typical
cycle for a significant change might include:

• General discussion of the idea, for example through a posting in a
  drupal.org forum.  This can be a chance to gauge support and interest, scope the issue, and get some
  direction and suggestions on approaches to take.  If you're considering
  substantive changes, starting out at the discussion level - rather than
  jumping straight into code changes - can save you a lot of time. 
• Posting an issue through the drupal.org project system.
• Discussion raising issues on the proposed direction or solution. 
  Individual Drupal community members may vote for (+1) or against (-1) the
  change.  While informal, this voting system can help quantify support.
• Producing a patch with specific proposed code changes.
• Review of the changes and further discussion.
• Revisions to address issues.
• Possible application of the patch.

The process of discussion and revision might be repeated several times to
encompass diverse input.  At any point in the process, the proposal might
be:

• Shelved as impractical or inappropriate.
• Put off until other logically prior decisions are made.
• Rolled into another related initiative.
• Superceded by another change.

If your suggestions don't end up being adopted, please don't be
discouraged!  It doesn't mean that your ideas weren't good--just that they
didn't end up finding a place.  The discussion itself may have beneficial outcomes. 
It's all part of collaboratively building a quality open source project.

The Structure of the Drupal Community

While the Drupal community is loosely defined, there are at least three
different levels of membership, with specific rights and responsibilities to
each.

• Core Developer.  Core developers have direct responsibility
  for maintaining and patching the Drupal software.  Core developers have
  write access on the Drupal CVS repository and typically have formal
  responsibility for a designated portion of the core (e.g., a particular core
  module).  While changes will take
  into account the views and comments of all members of the Drupal community,
  in the end it is the core developers who must decide on and make changes.
• Contributor.  Contributors develop and maintain
  "contributed" code (mainly, modules and themes).  A
  contributor has applied for and received write access to the
  "contributions" CVS repository and may also have
  special privileges on the drupal.org site enabling her or him to post
  content (book pages, new project releases) to the site.
• General member.  A general member of the Drupal community can
  make contributions by participating in the drupal.org forums and issue
  system and the drupal-dev email list, making suggestions and offering code
  contributions that others will evaluate and potentially apply either to
  contributed code or to the Drupal core.

Criteria for Evaluating Proposed Changes

The following criteria are used by core developers in reviewing and approving
proposed changes: 

• The changes support and enhance Drupal project aims as set out
  above.
• The proposed changes are current.  Especially for new features,
  priority is usually given to development for the "HEAD" (the most
  recent development version of the code, also referred to as the CVS version)
  as opposed to released versions.  There may have been significant
  changes since the last release, so developing for the CVS version means
  that 
• The proposed change doesn't raise any significant issues or
  risks.  Specifically, issues that have been raised in the review
  process have been satisfactorily addressed. 
• The changes are well coded. At a minimum, this means coding in accordance with the Drupal coding standards. But
  it also means that the coding is intelligent and compact.  Elegant
  solutions will have greater support than cumbersome ones that accomplish the
  same result.
• There is demonstrated demand and support for the change.  Demand
  is indicated by, e.g., comments on the drupal.org issues system or comments
  in forums or the drupal-dev email list.
• The benefits of the change justifies additional code and resource
  demands.  Every addition to the code base increases the quantity of
  code that must be actively maintained (e.g., updated to reflect new design
  changes or documentation approaches).  Also, added code increases the
  overall Drupal footprint through, e.g., added procedure calls or database
  queries.  Benefits of a change must outweigh these costs.

Tips for Contributing to the Core

The following tips might improve the chances of your contributions being accepted:

• Be explanatory, provide descriptions and illustrations, make a good
  case.  Don't count on others downloading, installing, and testing your
  changes.  Rather, show them in a nutshell what your changes would
  mean.  Anticipate and address questions or concerns.  If
  appropriate, provide screenshots.
• Be friendly and respectful.  Acknowledge the effort others put in.
• Be open to suggestions and to other ways of accomplishing what you're
  aiming for.
• Be persistent.  If you don't get any response right away, don't
  necessarily give up.  If you're still convinced your idea has merit,
  find another way to present it.
• Respond, in a timely way, to suggestions, requests, or issues
  raised.  Revise your work accordingly.
• If some time has gone by, update your changes to work with the current CVS
  version.