DOC Document new class_description and deprecated DBEnum::flushCache()

en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md

@@ -28,6 +28,8 @@ use SilverStripe\ORM\DataObject;
 
 class Player extends DataObject
 {
+    private static $class_description = 'Sports player';
+
     private static $table_name = 'Player';
 
     private static $db = [

en/08_Changelogs/5.4.0.md

@@ -9,6 +9,7 @@ title: 5.4.0 (unreleased)
 - [Features and enhancements](#features-and-enhancements)
   - [Option to change `ClassName` column from enum to varchar](#classname-varchar)
   - [Reports quality of life updates](#reports-quality-of-life-updates)
+  - [New `class_description` configuration on `DataObject`](#class-description)
   - [Other new features](#other-new-features)
 - [API changes](#api-changes)
 - [Bug fixes](#bug-fixes)
@@ -45,6 +46,18 @@ The changes include:
 - Reports list is now paginated
 - [`Description`](api:SilverStripe\Reports\Report::description()) is now displayed in the list as a column
 
+### New `class_description` configuration on `DataObject` {#class-description}
+
+[`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) and [`BaseElement`](api:DNADesign\Elemental\Models\BaseElement) both seperately implemented a `description` configuration property which was used to describe the purpose of a given subclass. For `SiteTree` this is used when creating a new page in the CMS. For `BaseElement` this is used in the elemental blocks report. In both cases the purpose is the same - it provides additional context about the intended use case for a given subclass.
+
+We've now implemented this concept in `DataObject` directly with the new [`DataObject.class_description`](api:SilverStripe\ORM\DataObject->class_description) configuration property. It is now considered best practice to add a description of `DataObject` subclasses using this configuration. You can use the new [`DataObject::classDescription()`](api:SilverStripe\ORM\DataObject::classDescription()) and [`DataObject::i18n_classDescription()`](api:SilverStripe\ORM\DataObject::i18n_classDescription()) methods if you need a description of any `DataObject` class. Those methods already existed on `SiteTree` but have been moved up the hierarchy so they can be called on any `DataObject` class.
+
+For now this is only used in the same places that used to use the deprecated configuration, but future minor releases are likely to broaden the scope of its usage.
+
+As a part of this change, the [`SiteTree.description`](api:SilverStripe\CMS\Model\SiteTree->description) and [`BaseElement.description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration properties are now deprecated. Use `class_description` instead.
+
+The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with the `.DESCRIPTION` suffix for any `SiteTree` subclass) is also deprecated - use `SilverStripe\CMS\Model\SiteTree.CLASS_DESCRIPTION` instead.
+
 ### Other new features
 
 - A new [`BaseKernel::getBooted()`](api:SilverStripe\Core\BaseKernel::getBooted()) method has been added for checking whether the kernel has been booted yet or not.
@@ -166,6 +179,9 @@ The changes include:
 - [`TemplateParser`](api:SilverStripe\View\TemplateParser) has been deprecated. It will be renamed to `SilverStripe\TemplateEngine\TemplateParser`.
 - [`ElementalAreaController::removeNamespacesFromFields()`](api:DNADesign\Elemental\Controllers\ElementalAreaController::removeNamespacesFromFields()) has been deprecated. It will be removed without equivalent functionality to replace it.
 - [`BaseElement::updateFromFormData()`](api:DNADesign\Elemental\Models\BaseElement::updateFromFormData()) has been deprecated. It will be removed without equivalent functionality to replace it.
+- [`DBEnum::flushCache()`](api:SilverStripe\ORM\FieldType\DBEnum::flushCache()) has been deprecated. Use [`DBEnum::reset()`](api:SilverStripe\ORM\FieldType\DBEnum::reset()) instead.
+- The [`BaseElement.description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration property has been deprecated. Use [`DataObject.class_description`](api:SilverStripe\ORM\DataObject->class_description) instead.
+- The [`SiteTree.description`](api:SilverStripe\CMS\Model\SiteTree->description) configuration property has been deprecated. Use [`DataObject.class_description`](api:SilverStripe\ORM\DataObject->class_description) instead.
 
 ## Bug fixes