add deprecation chapter

docs/conceptual-guides/deprecation.md

@@ -0,0 +1,86 @@
+---
+myst:
+  html_meta:
+    "description": "Understanding deprecation in Plone - rationale, philosophy, and use cases"
+    "property=og:description": "Understanding deprecation in Plone - rationale, philosophy, and use cases"
+    "property=og:title": "Deprecation"
+    "keywords": "deprecation, Plone, Python, Node.js, React, philosophy, rationale, use cases"
+---
+
+(conceptual-deprecation-label)=
+
+# Deprecation
+
+This chapter describes the rationale and philosophy of deprecations in Plone.
+It is meant as a guide for how to think about deprecations in Plone core packages.
+
+```{seealso}
+For implementation details and code examples, see {doc}`/developer-guide/deprecation`.
+```
+
+(why-deprecation-label)=
+
+
+## Why deprecation
+
+Developers may need to get rid of old code, unify to a consistent API style, fix typos in names, move code or templates around, resolve technical debt, address security issues, or adapt to changes in external dependencies.
+
+When refactoring code, it's often necessary to move modules, functions, classes, and methods.
+It's critical not to break third party code imports from the old place.
+It's also important that usage of old functions or methods must work for a while to allow developers to migrate or update their code.
+
+Deprecated methods are usually removed with the next major release of Plone.
+Plone follows the [semantic versioning guideline](https://semver.org).
+
+
+## Help programmers without annoyance
+
+Developers should use code deprecations to support the consumers of the code, that is, their fellow Plone developers.
+From the consumer's point of view, Plone core code is an API.
+Any change may annoy them, but they feel better when deprecation warnings tell them how to adapt their code to the changes.
+
+Deprecations must always log at the level of warning.
+
+Deprecations should always answer the following questions.
+
+-   Why is the code gone from the old place?
+-   What to do instead?
+
+A short message is enough, such as the following examples.
+
+-   "Replaced by new API `xyz`, found at `abc.cde`".
+-   "Moved to `xyz`, because of `abc`".
+-   "Name had a typo, new name is `xyz`".
+
+All logging must be done only once, in other words, on the first usage or import.
+It must not flood the logs.
+
+
+## Use cases
+
+The following use cases describe when to deprecate.
+
+Rename
+:   Developers may want to rename classes, methods, functions, or global or class variables to get a more consistent API or because of a typo.
+    Never just rename.
+    Always provide a deprecated version that logs a verbose deprecation warning with information for where to import from in the future.
+
+Move objects
+:   For reasons described in {ref}`why-deprecation-label`, developers may need to move code around.
+    When imported from the old place, it logs a verbose deprecation warning with information of where to import from in the future.
+
+Deprecation of a whole Python or npm package
+:   A whole {ref}`Python package <python:tut-packages>` or [npm package](https://www.npmjs.com/) may be moved to a new location.
+
+    -   All imports still work.
+    -   Log deprecation warnings on first import.
+    -   The ZCML still exists, but is empty or includes the ZCML from the new place, if there's no auto import for `meta.zcml`.
+
+Deprecation of a whole released or installable package
+:   Plone developers provide a major release with no "real" code, but only backward compatible imports of the public API.
+    This will be done the way described above for a whole package.
+    The README clearly states why it was moved and where to find the code now.
+
+Deprecation of a GenericSetup profile
+:   These may have been renamed for consistency or are superfluous after an update.
+    Code does not need to break to support this.

docs/conceptual-guides/index.md

@@ -16,8 +16,9 @@ This part of the documentation provides explanation of concepts to deepen and br
 :maxdepth: 2
 
 choose-user-interface
-compare-buildout-pip
 distributions
+compare-buildout-pip
+deprecation
 package-management
 package-dependencies
 make-backend-build

docs/developer-guide/deprecation.md

@@ -0,0 +1,255 @@
+---
+myst:
+  html_meta:
+    "description": "How to implement deprecations in Plone, including Python, ZCML and templates."
+    "property=og:description": "How to implement deprecations in Plone, including Python, ZCML and templates."
+    "property=og:title": "Implement deprecations"
+    "keywords": "deprecation, zcml, template, jbot, Plone, Python"
+---
+
+(developer-deprecation-label)=
+
+# Implement deprecations
+
+This chapter describes how to enable deprecation warnings and best practices for implementing deprecations in Plone, Zope, and Python.
+
+```{seealso}
+For background on deprecation philosophy and use cases, see {doc}`/conceptual-guides/deprecation`.
+```
+
+
+## Enable deprecation warnings
+
+### Zope
+
+Zope does configure logging and warnings, so the steps below (under section Python) are not needed.
+
+Using `plone.recipe.zope2instance` add the option `deprecation-warnings = on` to the buildouts `[instance]` section.
+
+```ini
+[buildout]
+parts = instance
+
+[instance]
+recipe = plone.recipe.zope2instance
+...
+deprecation-warnings = on
+...
+```
+
+This adds this line to the `zope.conf` file:
+
+```
+debug-mode on
+```
+
+Without the recipe this can be set manually as well:
+In `zope.conf` custom filters for warnings can be defined.
+
+```xml
+...
+<warnfilter>
+    action always
+    category exceptions.DeprecationWarning
+</warnfilter>
+...
+```
+
+### Python
+
+Enable Warnings
+
+: Warnings are written to `stderr` by default, but `DeprecationWarning` output is surpressed by default.
+
+  Output can be enabled by starting the Python interpreter with the [-W \[all|module|once\]](https://docs.python.org/3/using/cmdline.html#cmdoption-W) option.
+
+  It is possible to enable output in code too:
+
+  ```python
+  import warnings
+  warnings.simplefilter("module")
+  ```
+
+Configure Logging
+
+: Once output is enabled it is possible to [redirect warnings to the logger](https://docs.python.org/3/library/logging.html#logging.captureWarnings):
+
+  ```python
+  import logging
+  logging.captureWarnings(True)
+  ```
+
+### Running tests
+
+In Plone tests deprecation warnings are not shown by default.
+The `zope.conf` setting is not taken into account.
+
+In order to enable deprecation warnings,
+the Python way with the `-W` command option must to be used.
+
+Given youre using a modern buildout with virtualenv as recommended,
+the call looks like so:
+
+```bash
+./bin/python -W module ./bin/test
+```
+
+
+## Deprecation best practice
+
+### Vanilla deprecation messages
+
+Python offers a built-in `DeprecationWarning` which can be issued using standard libraries `warnings` module.
+
+For details read the [official documentation about warnings](https://docs.python.org/3/library/warnings.html).
+
+In short it works like so
+
+```python
+import warnings
+warnings.warn('deprecated', DeprecationWarning)
+```
+
+### Moving whole modules
+
+Given a package `old.pkg` with a module `foo.py` need to be moved to a package `new.pkg` as `bar.py`.
+
+[zope.deprecation Moving modules](https://zopedeprecation.readthedocs.io/en/latest/api.html#moving-modules) offers a helper.
+
+1. Move the `foo.py` as `bar.py` to the `new.pkg`.
+2. At the old place create a new `foo.py` and add to it
+
+```python
+from zope.deprecation import moved
+moved('new.pkg.bar', 'Version 2.0')
+```
+
+Now you can still import the namespace from `bar` at the old place, but get a deprecation warning:
+
+> DeprecationWarning: old.pkg.foo has moved to new.pkg.bar.
+> Import of old.pkg.foo will become unsupported in Version 2.0
+
+### Moving whole packages
+
+This is the same as moving a module, just create for each module a file.
+
+### Deprecating methods and properties
+
+You can use the `@deprecate` decorator from [zope.deprecation Deprecating methods and properties](https://zopedeprecation.readthedocs.io/en/latest/api.html#deprecating-methods-and-properties) to deprecate methods in a module:
+
+```python
+from zope.deprecation import deprecate
+
+@deprecate('Old method is no longer supported, use new_method instead.')
+def old_method():
+    return 'some value'
+```
+
+The `deprecated` wrapper method is for deprecating properties:
+
+```python
+from zope.deprecation import deprecated
+
+foo = None
+foo = deprecated(foo, 'foo is no more, use bar instead')
+```
+
+### Moving functions and classes
+
+Given we have a Python file at `old/foo/bar.py` and want to move some classes or functions to `new/baz/baaz.py`.
+
+Here `zope.deferredimport` offers a deprecation helper.
+It also avoids circular imports on initialization time.
+
+```python
+import zope.deferredimport
+zope.deferredimport.initialize()
+
+zope.deferredimport.deprecated(
+    "Import from new.baz.baaz instead",
+    SomeOldClass='new.baz:baaz.SomeMovedClass',
+    some_old_function='new.baz:baaz.some_moved_function',
+)
+
+def some_function_which_is_not_touched_at_all():
+    pass
+```
+
+### Deprecating a GenericSetup profile
+
+Starting with GenericSetup 1.8.2 (part of Plone > 5.0.2) the `post_handler` attribute in ZCML can be used to call a function after the profile was applied.
+We use this feature to issue a warning.
+
+First we register the same profile twice. Under the new name and under the old name:
+
+```xml
+<genericsetup:registerProfile
+    name="default"
+    title="My Fance Package"
+    directory="profiles/default"
+    description="..."
+    provides="Products.GenericSetup.interfaces.EXTENSION"
+    />
+
+<genericsetup:registerProfile
+    name="some_confusing_name"
+    title="My Fance Package (deprecated)"
+    directory="profiles/some_confusing_name"
+    description="... (use profile default instaed)"
+    provides="Products.GenericSetup.interfaces.EXTENSION"
+    post_handler=".setuphandlers.deprecate_profile_some_confusing_name"
+    />
+```
+
+And in `setuphandlers.py` add a function:
+
+```python
+import warnings
+
+def deprecate_profile_some_confusing_name(tool):
+    warnings.warn(
+        'The profile with id "some_confusing_name" was renamed to "default".',
+        DeprecationWarning
+    )
+```
+
+### Deprecating a template position
+
+Sometimes we need to move templates to new locations. Since addons often use [z3c.jbot](https://github.com/zopefoundation/z3c.jbot) to override templates by their position, we need to point them to the new position as well as make sure that the override still works with the old position.
+
+
+To deprecate a package:
+
+1. In the old package folders `__init__.py` add a dictionary `jbot_deprecations` that maps the old template locations to their new counterparts, e.g.:
+
+```python
+jbot_deprecations = {
+    "plone.locking.browser.info.pt": "plone.app.layout.viewlets.info.pt"
+}
+```
+
+2. Add this deprecation snippet to the package `configure.zcml` file:
+
+```{code-block} xml
+:emphasize-lines: 7-14
+:linenos:
+
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:browser="http://namespaces.zope.org/browser"
+    xmlns:zcml="http://namespaces.zope.org/zcml"
+    >
+
+  <include
+      zcml:condition="installed z3c.jbot"
+      package="z3c.jbot"
+      />
+  <browser:jbotDeprecated
+      zcml:condition="have jbot-deprecations"
+      dictionary=".jbot_deprecations"
+      />
+
+</configure>
+```
+
+If a `z3c.jbot` version that supports deprecation is found, trying to override the template with the old location will trigger a deprecation warning that will instruct the user to rename its override file.

docs/developer-guide/index.md

@@ -25,4 +25,5 @@ develop-volto-add-ons-index
 create-a-distribution
 standardize-python-project-configuration
 native-namespace
+deprecation
 ```