[docs] Add class properties deprecation guidelines

Documents the process for deprecating class properties, which cannot
emit runtime warnings in PHP < 8.4.

Key points:
- Private properties: remove immediately
- Protected properties in non-extensible classes: can be removed
- Public/protected properties in extensible classes: use @deprecated
  tags, attributes, and provide getter/setter methods with warnings
- From Moodle 6.0 (PHP 8.4+): use property hooks for proper deprecation

Author: meirzamoodle

general/development/policies/deprecation/index.md

@@ -205,6 +205,111 @@ A code removal step was added to the deprecation process in Moodle 5.0 and is al
     - Functions deprecated in Moodle 4.5 (LTS) will be up for final deprecation in Moodle 6.0 (the first release for Series 6 right after the Moodle 5.3 (LTS) release), and for removal in Moodle 7.0 (the first Series 7 Moodle version).
 </ValidExample>
 
+## Class properties deprecation
+
+Deprecating class properties presents unique challenges compared to methods, as PHP versions before 8.4 do not provide a native mechanism to emit warnings when properties are accessed or modified.
+
+### When can a property be deprecated?
+
+The approach to deprecating a property depends on its visibility and usage:
+
+1. **Private properties**: Can be removed immediately as they are not part of the public API.
+
+2. **Protected properties in non-extensible classes**: Can be removed if there is no reasonable expectation that external code extends the class. This applies to classes where:
+   - The API is not designed to be extended
+   - It would be extremely difficult for developers to correctly extend and consume the class
+   - The protected property is not considered part of the 'public' API
+
+3. **Public properties, or protected properties in extensible classes**: Cannot be safely removed using the standard deprecation process, as there is no way to alert developers when the property is accessed in PHP versions before 8.4.
+
+### Deprecation process for properties that cannot be removed
+
+For public properties and protected properties in extensible classes, follow these steps:
+
+1. **Add the `@deprecated` PHPDoc tag** to the property documentation, including:
+   - The version it was deprecated in.
+   - The reason for deprecation.
+   - Alternative approaches or replacement properties.
+
+   ```php
+   /**
+    * @var string
+    * @deprecated since 4.4 Use get_summary() method instead
+    */
+   public string $summary;
+   ```
+
+2. **Document in upgrade notes**: Ensure the deprecation is clearly documented in the [upgrade notes](../../upgradenotes.md) for the release.
+
+3. **Add the `\core\attribute\deprecated` attribute**:
+
+   ```php
+   #[\core\attribute\deprecated(
+       since: '4.4',
+       reason: 'Direct property access is deprecated. Use get_summary() and set_summary() methods instead.',
+       mdl: 'MDL-XXXXX',
+   )]
+   public string $summary;
+   ```
+
+4. **Ensure there are no internal uses**: Remove all usage of the property within Moodle core code, replacing it with the recommended alternative (such as getter/setter methods).
+
+5. **Provide getter/setter methods**: If the property previously had direct access, create getter and setter methods that:
+   - Provide the same functionality.
+   - Can emit deprecation warnings when the underlying property is accessed.
+   - Serve as the migration path for developers.
+
+   ```php
+   /**
+    * Get the summary text.
+    *
+    * @return string
+    */
+   public function get_summary(): string {
+       return $this->summary;
+   }
+
+   /**
+    * Set the summary text.
+    *
+    * @param string $summary The summary text
+    */
+   public function set_summary(string $summary): void {
+       if ($summary !== $this->summary) {
+           debugging(
+               'Direct property access to $summary is deprecated. Use set_summary() instead.',
+               DEBUG_DEVELOPER
+           );
+       }
+       $this->summary = $summary;
+   }
+   ```
+
+### Property deprecation from Moodle 6.0 onwards
+
+From Moodle 6.0, the minimum supported PHP version will be 8.4. PHP 8.4 introduces [Property Hooks](https://wiki.php.net/rfc/property-hooks), which allow proper deprecation warnings to be emitted when properties are accessed or modified.
+
+**Example using PHP 8.4 property hooks:**
+
+```php
+#[\core\attribute\deprecated(
+    since: '4.4',
+    reason: 'The "summary" attribute on the "table" element is not supported in HTML5. ' .
+            'Consider describing the structure of the table in a "caption" element or in a ' .
+            '"figure" element containing the table; or, simplify the structure of the table ' .
+            'so that no description is needed.',
+    mdl: 'MDL-XXXXX',
+)]
+public ?string $summary {
+    set {
+        \core\deprecation::emit_deprecation([self::class, __PROPERTY__]);
+        $this->summary = $value;
+    }
+}
+```
+
+This allows Moodle to emit proper runtime deprecation warnings when properties are written to, providing the feedback mechanism that is currently unavailable in earlier PHP versions.
+
 ## Parameters deprecation
 
 Whilst it is possible to deprecate individual method parameters, care must be taken in doing so.