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.