kitf.txt

   1
   2 KIT Feature Specification (kitf 1.0-draft)
   3 ------------------------------------------
   4 This document provides recommendations and requirements for Drupal features to
   5 ensure the interoperability of features between different distributions and
   6 prevent conflicts between features themselves and between a compliant feature
   7 and a distribution.
   8
   9 This document is based on the Drupal 6.x versions of Drupal core, contributed
  10 modules and themes.
  11
  12
  13 1. Introduction
  14 ---------------
  15 A feature is a Drupal module that provides a collection of Drupal entities which
  16 taken together satisfy a certain use case. A feature module differs from a
  17 standard Drupal module in several ways:
  18
  19 - A feature is built to target one or more use cases - concrete, task-specific
  20 functionality - not address a general problem space.
  21 - The bulk of a feature's work is to provide exported configuration, either in
  22 the form of exportables or scripted configuration of components.
  23 - A feature provides no API of its own. Any custom code and hooks it may
  24 implement are targeted at addressing user stories.
  25
  26
  27 ### Terminology
  28
  29 - A **feature** is a Drupal module that provides a collection of Drupal entities
  30 which taken together satisfy a certain use case. Example:a gallery feature
  31 provides a gallery view, a photo content type, and several blocks allowing a
  32 user to add new photos and browse those submitted by others.
  33 - A **component** is an individual object or configured setting provided by a
  34 feature. Example: a `gallery` view, the `comment_gallery` variable.
  35 - A **distribution** or **distro** is a a fully configured and usable Drupal
  36 instance. It can refer to a specific install profile or a single, custom Drupal
  37 site that has been setup and configured manually. Example: Open Atrium, a
  38 personal blog at http://example.com/myblog
  39
  40
  41 ### Feature creation
  42
  43 The specific methods used to create and implement a feature are not prescribed
  44 by this document. For our purposes, any of the following are acceptable methods
  45 of implementing a feature:
  46
  47 - Exporting components and writing their default hooks by hand to a custom
  48 module.
  49 - Scripting the creation of components and/or enforcing settings at install
  50 time.
  51 - Using the [Features module](http://drupal.org/project/features) to generate a
  52 feature from exportable components.
  53
  54
  55 ### Declaring compliance
  56
  57 Features compliant with this specification may declare themselves as such in
  58 their module `.info` file using the `kitf` key and the version of this document
  59 to which they comply. Example:
  60
  61     kitf = "1.0-draft"
  62
  63
  64 ### Distro features
  65
  66 Some features cannot comply with this specification and should not aim to.
  67 Features that package configuration above and beyond any specific user stories
  68 or play a setup and site configuration role similar to install profiles are
  69 called distro features. Kit compliant features can expect distro features to
  70 claim variables like `site_frontpage` and permissions like `access content`.
  71
  72
  73 2. Namespaces
  74 -------------
  75 The naming of a feature and its components are critical to its viability as a
  76 portable, interoperable module. Namespace conflicts can prevent code from
  77 execution and poor naming conventions can confuse users and other developers.
  78
  79
  80 ### 2.1 Code namespace
  81
  82 The code namespace includes a prefix to all PHP functions, the directory name of
  83 the feature module, and the names of files used by that feature module.
  84
  85 - A feature must, to the best of the creator's knowledge, use a unique code
  86 namespace.
  87 - Example: `dazzle_blog`, not `blog`
  88
  89
  90 ### 2.2 Project namespace
  91
  92 The project namespace is the key used for retrieving a project's update XML
  93 feed.
  94
  95 - Where possible, a feature's project namespace should match its code namespace.
  96 A feature's project namespace may be different from its code namespace if it is
  97 to be bundled with others and share an update XML feed.
  98 - Example: `dazzle_blog`, `dazzle_features`, `dazzle`
  99
 100
 101 ### 2.3 Machine name
 102
 103 The machine name is the machine-readable name that best describes the use case
 104 captured by a feature.
 105
 106 - A feature's machine name need not be unique.
 107 - Example: `blog`, `gallery`, `timetracker`
 108
 109
 110 ### 2.4 Human readable name
 111
 112 The human readable name of a feature is the name displayed in the Drupal admin
 113 UI for the feature as well as the name used for a feature in documentation and
 114 conversation.
 115
 116 - A feature's human readable name need not be unique.
 117 - Example: Blog, Gallery, Time Tracker
 118
 119
 120 ### 2.5 Component namespace
 121
 122 The component namespace is the naming convention used for any components (views,
 123 content types, etc.) included in a feature.
 124
 125 - A feature's component namespace need not be unique. Each component name should
 126 be prepended by the feature machine name whenever possible.
 127 - Example: `blog_listing`, not `recent_blog_posts`
 128
 129
 130 3. User roles and permissions
 131 -----------------------------
 132 A feature should provide default role and permission settings for permissions
 133 that are tightly related to its functionality. Properly implemented, a feature
 134 should be usable immediately after being enabled with proper permissions for
 135 most scenarios.
 136
 137
 138 ### 3.1 Required user roles
 139
 140 The following use roles must be accounted for in any permissions that are
 141 exported or configured by a feature:
 142
 143 - `anonymous user` is a Drupal user who has not been authenticated on the site.
 144 - `authenticated user` is a Drupal user who has been authenticated and is
 145 currently logged in on the site.
 146 - `administrator` is a Drupal user with administrative duties and is expected
 147 to perform site building and configuration tasks.
 148
 149 Additional roles may be provided by a feature if appropriate for its use case.
 150
 151
 152 ### 3.2 Permissions
 153
 154 Permissions exported or configured by a feature must be **directly** related to
 155 a feature's use case and functionality. Permissions that are unrelated or apply
 156 to a variety of other possible functionalities must not be included with a
 157 feature. A general rule of thumb is to ask whether the feature can function
 158 sufficiently without the permission in question configured. If possible, the
 159 permission should be left to the distro to configure instead.
 160
 161 - Example: A blog feature may include `create blog content`, `delete own blog
 162 content`, `edit own blog content` permissions. It may not include `administer
 163 nodes`, `access all views`, `access administration pages`.
 164
 165
 166 ### 3.3 Restricted permissions
 167
 168 The following list of permissions are examples of permissions that are
 169 considered restricted from use by a feature. It is by no means an exhaustive
 170 list nor a strict one. Some features may have a strong reason to include one or
 171 more of these permissions in order to implement its use case. For example, a
 172 feature that directly affects the authentication process of Drupal may have good
 173 claim to the permission `change own username`. In all other cases, configuration
 174 of these permissions should be left to the distro.
 175
 176     block
 177       administer blocks
 178       use PHP for block visibility
 179     comments
 180       access comments
 181       administer comments
 182       post comments
 183       post comments without approval
 184     filter
 185       administer filters
 186     menu
 187       administer menu
 188     node
 189       access content
 190       administer content types
 191       administer nodes
 192       delete revisions
 193       revert revisions
 194       view revisions
 195     search
 196       administer search
 197       search content
 198       use advanced search
 199     system
 200       access administration pages
 201       access site reports
 202       administer actions
 203       administer files
 204       administer site configuration
 205       select different theme
 206     taxonomy
 207       administer taxonomy
 208     upload module
 209       upload files
 210       view uploaded files
 211     user module
 212       access user profiles
 213       administer permissions
 214       administer users
 215       change own username
 216
 217
 218 4. Variables
 219 ------------
 220 Like permissions, a feature may configure default values for variables where
 221 they **directly** relate to a feature's use case. Variables that are unrelated
 222 to a feature's use case or apply to a more general range of use cases must not
 223 be included.
 224
 225 - Example: A blog feature may include `comment_blog`, `node_options_blog`,
 226 variables. It may not include `site_frontpage`, `teaser_length`,
 227 `user_register`.
 228
 229
 230 ### 4.1 Restricted variables
 231
 232 The following list of variables are examples of variables that are considered
 233 restricted from use by a feature. Like the permission list in 3.3, it is meant
 234 to illustrate variables that are often more general than the use cases commonly
 235 targeted by individual features. Like permissions, exceptions exist where it
 236 makes sense for a feature to make claim to one of the listed variables.
 237
 238     dblog
 239       dblog_row_limit
 240     filter
 241       filter_default_format
 242     menu
 243       menu_default_node_menu
 244       menu_primary_links_source
 245       menu_secondary_links_source
 246     node
 247       default_nodes_main
 248       node_preview
 249       teaser_length
 250     path
 251       clean_url
 252     search
 253       minimum_word_size
 254       overlap_cjk
 255       search_cron_limit
 256     statistics
 257       statistics_count_content_views
 258       statistics_enable_access_log
 259       statistics_flush_accesslog_timer
 260     system
 261       admin_theme
 262       anonymous
 263       block_cache
 264       cache
 265       cache_lifetime
 266       clean_url
 267       configurable_timezones
 268       date_default_timezone
 269       date_first_day
 270       date_format_long
 271       date_format_long_custom
 272       date_format_medium
 273       date_format_medium_custom
 274       date_format_short
 275       date_format_short_custom
 276       error_level
 277       feed_default_items
 278       feed_item_length
 279       file_downloads
 280       image_toolkit
 281       node_admin_theme
 282       page_compression
 283       preprocess_css
 284       preprocess_js
 285       site_403
 286       site_404
 287       site_footer
 288       site_frontpage
 289       site_mail
 290       site_mission
 291       site_name
 292       site_offline
 293       site_offline_message
 294       site_slogan
 295       theme_default
 296       user_pictures
 297     taxonomy
 298       taxonomy_override_selector
 299       taxonomy_terms_per_page_admin
 300     throttle
 301       throttle_anonymous
 302       throttle_probability_limiter
 303       throttle_user
 304     update
 305       update_check_frequency
 306       update_fetch_url
 307       update_last_check
 308       update_max_fetch_attempts
 309       update_notification_threshold
 310       update_notify_emails
 311     upload
 312       upload_extensions_default
 313       upload_list_default
 314       upload_max_resolution
 315       upload_uploadsize_default
 316       upload_usersize_default
 317     user
 318       user_email_verification
 319       user_mail_status_activated_notify
 320       user_mail_status_blocked_notify
 321       user_mail_status_deleted_notify
 322       user_picture_default
 323       user_picture_dimensions
 324       user_picture_file_size
 325       user_picture_guidelines
 326       user_picture_path
 327       user_pictures
 328       user_register
 329       user_registration_help
 330       user_signatures
 331
 332
 333 5. Paths and menu items
 334 -----------------------
 335 A feature may implement new Drupal pages and menu items by registering paths
 336 through `hook_menu()` or through another providing module. A feature may also
 337 override existing paths directly related to its use case using
 338 `hook_menu_alter()`.
 339
 340
 341 ### 5.1 Primary path
 342
 343 The primary path of a feature is the most prominent page path which provides the
 344 starting or entry point to a feature's provided functionality. Some features may
 345 not have a primary path.
 346
 347 - A feature's primary path should match its machine name where possible.
 348 - Example: A blog feature should have a primary path of `blog`, not `news` or
 349 `latest-blog-posts`.
 350
 351
 352 ### 5.2 Primary menu item
 353
 354 The primary menu item of a feature is a menu item corresponding to the primary
 355 path of a feature. Some features (including those with a primary path) may not
 356 have a primary menu item.
 357
 358 - A feature's primary menu item may be placed in any Drupal menu.
 359 - A feature's primary menu item should be titled using the feature's human
 360 readable name where possible.
 361 - Example: A blog feature should provide a primary menu item with the title
 362 "Blog".
 363
 364
 365 ### 5.3 Additional paths and menu items
 366
 367 Additional paths and menu items may be titled as seen fit by the feature
 368 creator.
 369
 370
 371 ### 5.4 Reserved paths
 372
 373 The following list of paths are examples of paths that are considered restricted
 374 from use by a feature. Like the permission list in 3.3, it is meant to
 375 illustrate paths that are often more general than the use cases commonly
 376 targeted by individual features. Like permissions, exceptions exist where it
 377 makes sense for a feature to make claim to one of the listed paths.
 378
 379     node
 380       node/%node
 381       node/add
 382       rss.xml
 383     search
 384       search
 385     taxonomy
 386       taxonomy/term/%
 387
 388
 389 6. Block visibility and theme regions
 390 -------------------------------------
 391 A feature may configure block visibility settings for blocks that **directly**
 392 provide functionality related to its use case. It may not configure or alter the
 393 block visibility settings of other blocks.
 394
 395 - Example: A blog feature may set visibility settings for a "Recent comments"
 396 block. It may not adjust visibility settings for the "User login" block.
 397
 398
 399 ### 6.1 Theme regions
 400
 401 Drupal's theme layer allows themes to implement any number of custom regions and
 402 omit ones referenced by the default core theme Garland. A feature should one of
 403 the following regions for blocks critical to its functionality and can expect a
 404 compliant theme to support them.
 405
 406 - `content`: The main page content region.
 407 - `left`: The lefthand sidebar.
 408 - `right`: The righthand sidebar.
 409
 410 Other regions may be used for non-critical blocks.
 411
 412
 413 7. Dependencies
 414 ---------------
 415 A feature may not depend on a module or feature that is not in compliance with
 416 any of the requirements in this spec.
 417
 418
 419 8. Problematic components
 420 -------------------------
 421 Components that fail to provide proper exportables, especially those using
 422 serial IDs as the primary method of manipulating and referencing their
 423 configuration objects, can be critical blockers to a feature's interoperability.
 424 The following is a list of modules with known interoperability issues:
 425
 426 - `filter`: serial `fid` for input formats
 427 - `nodequeue`: serial `qid` for nodequeues
 428 - `taxonomy`: serial `vid` for vocabularies
 429 - `wysiwyg`: see filter