debutf.txt in Debut 7

Debut Feature Specification (debutf 1.0-draft)
----------------------------------------------
Extending the kitf feature specification, this document provides a set of
requirements for Drupal features to provide suitable baseline functionality
suitable to various distributions and individual site installs and at the
same time integrate effectively into a cohesive feature set. Debut features
should together provide an integrated set of functionality that covers the
basic needs of most Drupal websites and distributions.

This document is based on the Drupal 7.x versions of Drupal core, contributed
modules and themes.


1. Introduction
---------------
The kitf feature specification provides important guidelines and requirements
to ensure interoperability among Drupal features.

Building on kitf, Debut features are based on the following precepts:

* Debut features should provide the basic functionality that most sites or
distributions will need.
* Any advanced or specialized functionality should be provided in separate
features that require more basic features.
* The ease of discovery and use of website feature for both admins and end
users should be an overriding goal.
* Every main task should have only one primary admin interface.
* Common protocols and solutions should be used to ensure consistency and ease
of use.

### Uniqueness and compatibility

Wherever possible, each Debut feature should cover a unique area of
functionality. For example, there should be only a single Debut feature
that provides general blog functionality. Exceptions can be made where the
underlying framework used is radically different and there is no common
base to build on.

### Available on the Drupal infrastructure

To ensure visibility, all Debut features should be hosted on the Drupal
infrastructure.

### Declaring compliance

Features compliant with this specification may declare themselves as such
in their module `.info` file using the `debutf` key and the version of this
document to which they comply. Example:

    debutf = "1.0-draft"

### Features framework

A feature should meet its needs through Features-aware solutions wherever
possible. Where multiple options exist, a primary selection criterion should be
how fully they embrace the Features framework.

- Context: Where context or contextual layout is required, the Context module
should be used.
- Boxes: Where custom blocks are required, the Boxes module must be used.
- Strongarm: Where variables are set, the Strongarm module should be used.
- Spaces: Where individual items (user spaces, pieces of content) require
contextual customization, the Spaces module should be used.

One of the most challenging tasks for novice site admins is controlling layout
of individual sections or pages. The Panels module is a highly advanced and
powerful solution for this purpose, but using Panels in combination with
Context is demanding and error-prone. If e.g. a node type is overridden with
a panel page, this panels page must be created by a single feature--barring
custom coding, there is no easy way for other features to selectively add
panes such that the overall panels page is constructed from the contributions
of whatever other features are enabled. For this reason, Context rather than
Panels seems the best overall choice for building displays in Debut.

### Standard solutions

To help produce uniformity among the various Debut features, standard solutions
are adopted across Debut. For example, for mapping, there are several Drupal
modules available, e.g., Gmap, OpenLayers. To ensure consistency, one should
be designated as the Debut standard.

In selecting between alternatives, the Drupal principles
(http://drupal.org/principles) are to be used as well as the following
additional criteria:

* Community open source: the candidate solution is a community-driven open
source solution.
* Non-proprietary: The candidate solution is not limited to, branded by, or
controlled by a single company.
* Data security: The candidate solution does not require posting data to an
external source unless doing so is the explicit purpose.
* Works out of the box without requiring manual configuration, e.g., entry of
an API key.

Before introducing a new Debut feature that introduces a dependency that could
be considered as a new standard solution, an issue must be posted on the Debut
project proposing the new standard solution with justification.

Adopted standard solutions:

- Captcha: where forms are protected from automated submission, the Captcha
module should be used.
- OpenLayers: where client side mapping is required, the OpenLayers Drupal
module should be used.
- Pathauto: where appropriate, paths variables should be set so that, if
Pathauto is present, content types defined by a feature will get appropriate
paths.
- Rules should be used and not the core Trigger module for any configurable
actions.

### Opportunity for peer review

There should be an opportunity for review prior to a new Debut feature being
posted. Such review will help ensure that new features indeed meet the Debut
spec, e.g.,

* identify any potential components that could/should be pulled into more
specific Debut features,
* identify properties that are too site-specific to warrant inclusion in Debut,
* if the feature introduces a new solution to standardize (e.g., an external
library or a way to structure particular data), ensure a consensus prior
to adoption.

Therefore each proposed Debut feature should be posted first as an issue on the
Debut project, with a link to the sandbox version of the proposed feature and
two weeks allowed for peer review prior to the new feature being promoted from
a sandbox project to a full project on drupal.org.

### Soft vs. hard configuration

A distinction should be made between "soft" and "hard" configuration.

Soft configuration is likely to be changed on a given site and doesn't require
or lend itself to updating in future code releases. Examples might include:

- A variable that controls which content types receive social media links. This
variable may be customized continuously as new content types are added to
the site.

Hard configuration is relatively unlikely to be customized on a given
site and/or lends itself to updating in a future feature release. Hard
configuration tends to be the core structure of a site. Examples might include:

- Content types and their fields.
- Views.

Hard configuration is properly handled by export into Features components.
However, soft configuration should live in the site database rather than code.
In general, soft configuration should be handled in hook_install() using
available API methods.


2. Namespaces
-------------

### 2.1 Code namespace

A Debut feature must include the debut namespace.

- Example: `debut_blog`.


### 2.2 Project namespace

A Debut project must include the debut namespace.

- Example: `debut_blog`.


3. User roles and permissions
-----------------------------

### 3.1 Required user roles

The `administrator` role defined in kitf should be used for site administration
tasks, such as installing and configuring modules, content types, and blocks.
The administrator role is defined by the Debut feature and so should not be
defined by any other Debut feature.

In addition to the three roles defined in kitf, features should use the
following two roles as appropriate.

- `contributor` is a Drupal user who contributes content, e.g., a staff member
at an organization or company.
- `editor` is a Drupal user responsible for editing and administrating content,
taxonomies, and comments.

These roles are provided by the Debut feature and so will be present if Debut
is installed. However, to avoid unwanted roles, Debut features should avoid
requiring the Debut feature if feasible.

A Debut feature may provide additional roles, but such roles should have a
scope no greater than the scope of the feature. For example, a blog feature
might provide a `blogger` role. However, a technology blog feature should not
provide a `blogger` role, since that role would be relevant to a more general
feature.

### 3.2 Permissions

Because Features will remove an existing permission from any role not
specified in an exported user permission, all permissions should be
explicitly assigned to the `administrator` role.

The editor role should not be expected to have `administer nodes` permissions.

For each content type introduced, roles should be assigned as follows:

- `contributor`: `create [type] content`, `delete own [type] content`, `edit
own [type] content`
- `editor`: `create [type] content`, `delete all [type] content`, `edit all
[type] content`

where [type] is the machine name of the content type being introduced by the
feature.


4. Variables
------------
A feature should include a settings form for any variables important to it.
Doing so will facilitate Spaces integration.


5. Paths and breadcrumbs
-----------------------

### 5.1 Primary path and nesting

Where a feature provides content or nested pages, these should wherever
feasible be available at paths nested below the feature's primary path.

Without creating a dependency on Pathauto, a feature that defines a content
type should register a pathauto pattern variable that nests content of that
type below the feature's primary page.

Example: a blog feature would use Strongarm to set pathauto_node_audio_pattern
to 'blog/[title-raw]'.

### 5.2 Menu location and breadcrumbs

Menu location and breadcrumbs for pages created by the feature should match the
nesting used for paths.

Context should be used to set breadcrumbs. For example, an article feature
including an article content type and an article landing page at 'article'
should set a context breadcrumb reaction on article node pages pointing to the
'article' menu item.

Currently context includes a menu class reaction but doesn't set the menu
trail.

See http://drupal.org/node/835090 for a potential menu trail context reaction.

In general, menu items should be treated as "soft" configuration and created
via API calls in hook_install().


6. Block visibility and theme regions
-------------------------------------

### 6.1 Block visibility

The Context module should be used wherever feasible for block placement and
visibility. 

### 6.2 Theme regions

Only the theme regions specified in kitf may be used. Pending a Drupal 7
version of kitf, those regions are:

* `content`
* `sidebar_first`
* `sidebar_second`

The sidebar_second region should be used primarily, with only occasional,
supplemental blocks being assigned to the sidebar_first region.


7. Dependencies
---------------
A feature may not depend on any feature that is not fully compliant with this
specification.

### Versions

Wherever feasible, features should use the recommended stable release versions
of contributed modules and themes.

### Libraries

Any external libraries used by a feature should be installed in a libraries
directory if possible.

### Patches

Patches should be avoided wherever possible. Ideally, patches should be used
only up to and including beta releases, to include functionality expected
to reach stable releases by the time the feature is out of beta.

Where feasible, patches should be replaced with workarounds in a feature's
.module file that use Drupal APIs to achieve the same ends. These workarounds
should include documentation identifying the patch that they relate to so
they can be removed if/when that patch is accepted.

### Drush make file

A feature should include a sample Drush make file including all the feature's
dependencies (modules, external libraries, etc.) that would typically be
installed with the feature.

To avoid being automatically processed by Drush Make, make files should end
with a .inc extension.

For example, a debut_wysiwyg feature might include debut_wysiwyg.make.inc
including the wysiwyg project, other required and optional modules, and a
WYSIWYG library like ckeditor.

To ensure that any modules or libraries declared in one feature don't duplicate
those in another, the following path convention must be used:

- contrib: used for all code in Drupal's version control
- external: used for modules, themes, etc. hosted externally, e.g., modules on
Github.

Examples:

; A drupal.org hosted project.
projects[views][subdir] = contrib
; An externally hosted project.
projects[seed][subdir] = external
projects[seed][location] = http://code.developmentseed.org/fserver


8. Content types and fields
---------------------------

Where a feature defines a content type, the following guidelines should be
followed:

### Image and other media fields

* If a single image is desired to represent each piece of content in the
content type, the content type should use field_content_image as used in e.g.
debut_article.
* If media (images, audio, video, files) are desired, the content type should
use field_media as used in e.g. debut_article.


9. Views
--------

For consistency, the following conventions should be used for views included in
features.

* Naming: if the view is primarily for presenting a single content type, it
should be named for the machine name of that content type.
* At a minimum, views of a content type should include a page, block, and
feed display, with the feed display attached to both the page and block. The
page display should have a path matching the content type's machine name
and the feed should have the same path with an .xml extension.


10. Contexts
------------

Where appropriate, features that define a content type should include a context
that displays related content on node pages of that content type. For example,
an event feature might display a calendar block and an upcoming events block
when event content is being viewed.

For consistency, unless there are extenuating reasons, such contextual blocks
should be placed in the sidebar_second region.


11. Help
--------

A feature may include contextual help provided through the Advanced Help
module covering major components of the feature.