Plan for DateTime Range experimental module

Problem/Motivation

Related to #2161337: Add a Date Range field type with support for end date

People want to have datetimes with start and end dates.

Proposed resolution

Add DateTime Range as an experimental module https://www.drupal.org/core/experimental

Proposal roadmap

Required sign-off before commit

For this module to become a stable part of Drupal core, all of the "Must-have" and most "Should-have" followups should be completed before the beta phase for 8.4.0.

Must-have

https://www.drupal.org/core/experimental#requirements

Experimental modules are not subject to the same rigorous quality standards as stable Drupal core modules and do not yet need to meet all the Drupal core gates. They can be added with known architectural issues, imperfect coding standards (so long as they do not fail automated checks), minimal UIs, outstanding issues, etc.

These must-haves will need to be completed prior to 8.4.0-beta1.

• #2849758: [no patch] Verify removing the datetime_range module can be done without lasting disruption
• create followups to meet the core gates.
  • Usability review, including #2788359: datetime_wrapper improperly applied to DateTimeWidgetBase
  • Accessibility fixes including #1918994: Improve Datetime and Daterange Widget accessibility and probably an additional followup for the datetime_range field itself (see #2161337-319: Add a Date Range field type with support for end date and https://www.drupal.org/files/issues/Screen%20Shot%202016-08-19%20at%209....).
• datetime_range_help() - done
• Are there other issues not included here? Please add them to the issue.

Should-have

• Translatable string context for field labels: #2796145: Daterange field labels not specific enough
  

  It would be nice to add "context" to the start and end strings so that someone translating those interface strings would know they have to deal with dates.

• Discuss whether to make BC changes to datetime in DateTimeDefaultFormatter, DateTimePlainFormatter etc. related to the buildDate() trait (see https://www.drupal.org/files/issues/2161337-missing-hunks.txt).
• #2775669: Clean up redundant methods in datetime field formatters
• RTL. #2787105: Add RTL support for daterange formatters Working as designed, see #2787105-6: Add RTL support for daterange formatters, #2788253-45: Plan for DateTime Range experimental module
• #2796151: Date range separator should be translatable
• Make "DateTime Range" appear immediately under "DateTime" in the field selector (should probably happen before module is added to Standard).
• #2863444: Discourage/make impossible to select a "to" date that is before the "from" date (should happen before module is added to Standard if not before it's marked stable).

Could-have

• Daterange specific argument, filter, and sort Views plugins: #2786577: Improve the Views integration for DateRange fields

• This trait is specific to formatters, so perhaps rename to DateTimeRangeFormatterTrait? And maybe also move into the Drupal\datetime_range\Plugin\Field\FieldFormatter namespace?

• Finally, if we're rerolling this patch anyway with any changes to the trait for the above, should we also move defaultSettings(), settingsForm(), and settingsSummary() to the trait, since those are identical between the 3 formatters? Even viewElements() could almost be moved there, so long as DateRangeDefaultFormatter could extend the trait's method and additionally handle the $item->_attributes logic.

• Allow templating of the whole formatter to make date ranges easy to customize (beyond just the configurable separator), #2876434: Datetime Range fields should provide a template
• Or, if templating is not provided, consider moving the space into the separator:
  

  +++ b/core/modules/datetime_range/src/Plugin/Field/FieldFormatter/DateRangeCustomFormatter.php
  @@ -0,0 +1,96 @@
  +            'separator' => ['#plain_text' => '' . $separator . ''],
  
  +++ b/core/modules/datetime_range/src/Plugin/Field/FieldFormatter/DateRangeDefaultFormatter.php
  @@ -0,0 +1,104 @@
  +      

  This hardcodes the spaces surrounding the separator, should we move those into the separator variable instead?

• Should the separator support HTML entities? (But: still ensure it's sanitized.)
• https://www.drupal.org/node/2863439

Already complete in the experimental prototype (or not applicable)

• check for security issues.
• check for data integrity issues.
• verify no disruption or regression to stable functionality
• verify functional test coverage exists for the primary usecase, with no test failures in HEAD
• document Ideas/prototypes for user interfaces that are planned
• minimally validate prototypes for user interfaces
• document any critical issues that maintainers identify as hard blockers
• verify any critical issues that maintainers identify as hard blockers, are fixed
• open followups for additional test coverage that might be needed in the future
• verify basic API documentation exists for the minimum requirements
• document a timeframe for completing the remaining work (typically two minor releases), a plan for addressing followups, and roughly which followups must be completed to keep the module in core.
• Verify UI, API, Data module changes in this issue summary, they were copied from #2161337: Add a Date Range field type with support for end date
• document a plan/open followups for completing more comprehensive documentation in the codebase and handbook (what topics are needed)

Final Steps

• #2893128: Remove datetime_range from experimental package
• #2893127: Add datetime_range to the Standard Profile

Review notes

When reviewing proposed experimental modules, consider whether your feedback is part of these minimal requirements, or whether it should instead be followup work as part of making the experimental module stable. If it does not need to block commit, post a followup issue on the roadmap instead of commenting on the initial patch.

[add more notes that are helpful for reviewers]

Contributed projects

https://www.drupal.org/project/datetime_extras

User interface changes

New field widgets.

API changes

New field type and associated goodness.

Data model changes

New schema for date ranges.