add deprecation chapter #1850

MrTango · 2025-02-11T12:58:43Z

First-time contributors

You must read and follow our First-time contributors.

Submit a pull request

Thank you for your contribution to the Plone Documentation.

Before submitting this pull request, please make sure you follow our guides:

Issue number

Fixes #

Description

Write a description of the fixes or improvements.

Add screenshots or links to a preview of the changes

📚 Documentation preview 📚:

docs/backend/deprecation.md

Co-authored-by: Alessandro Pisa <[email protected]>

docs/backend/deprecation.md

Co-authored-by: Alessandro Pisa <[email protected]>

jensens · 2025-12-05T00:25:49Z

Ok, this should work. @stevepiercy what do you think?

docs/developer-guide/deprecation.md

Co-authored-by: Alessandro Pisa <[email protected]>

ale-rt

Thank you very much to all of you :)
@stevepiercy do you mind having another look?

- Generalize for npm and Volto - Clean up MyST style and formatting

- Clean up grammar, MyST syntax - Indent code within list items. - Use ruff style code example formatting.

stevepiercy

This is really good. I can tell because even I can understand it.

I have only one question that needs to be addressed. Thank you!

jensens · 2025-12-15T16:36:55Z

This is really good. I can tell because even I can understand it.

I have only one question that needs to be addressed. Thank you!

sorry, I can not find the question...

stevepiercy · 2025-12-15T17:59:44Z

docs/developer-guide/deprecation.md

+
+### Zope
+
+Zope configures logging and warnings, so the steps as described below in {ref}`deprecation-warning-python-label` aren't needed.


If the steps in the next section aren't needed, then why do we include them?

With next step you refer to debug-mode on? IIRC it is needed to show the messages. I wrote this down years ago, so this may have been subject to change.

And with cookiecutter-zope-instance based installs we only need to use the PYTHONWARNINGS variable or start the interpreter with parameters (like below in Python).

Thinking further, I am not 100% sure if the above method is anyway ZServer only?
Does anybody in here know more details?

@jensens you might be able to see it more clearly on the pull request preview, beginning at https://plone6--1850.org.readthedocs.build/developer-guide/deprecation.html#zope.

This sentence refers to the next section entitled Python, and it states that the steps in that section are not needed.

We can drop the whole section Zope with plone.recipe.zopeinstance since this feature was dropped with WSGI server usage. So, it does not make sense to keep the Python subheading, right?
See last bullet point at https://github.com/plone/plone.recipe.zope2instance/blob/0452e05386708564b17ae1de1aafe708a4d88ccb/CHANGES.rst#610-2018-12-28

Shall we mention somehow this change in the developer guide or focus on the current state?

I wish I could offer advice, but this was before my time. I'll go with what you think is true and accurate, and to the best of your knowledge. We can also wait a few days for other old timers to offer advice. The only thing I can refer to is this search result:

https://6.docs.plone.org/search.html?q=plone.recipe.zopeinstance

I'd focus on the current state of Plone 6.x.x. I'd use a {versionchanged} or {versionremoved} MyST directive, but we should use Plone 6.x.x or 5.x.x as the referred version, whenever the package got released with Plone, not the package's version. The content of that directive should include whatever is helpful to Plone 6 developers for what has changed. There might even be some references in the Upgrade Guide. Why, yes, there is: https://6.docs.plone.org/backend/upgrading/version-specific-migration/upgrade-to-52.html#wsgi

Does that help at all?

We can drop the whole section Zope with plone.recipe.zopeinstance since this feature was dropped with WSGI server usage. So, it does not make sense to keep the Python subheading, right?

I think you mean we don't need to keep the Zope subheading. The Python subheading still seems accurate.

I must say I always get deprecation warnings when starting Plone though, even though I don't think I have configured anything to enable it. So when I don't want them, I explicitly disable them with export PYTHONWARNINGS=ignore. This may depend on how Python is installed, and with which flags it was built.

Shall we mention somehow this change in the developer guide or focus on the current state?

Indeed focus on current state, but if possible mention the change as Steve says.

We then have one subheading, that is a bit pointless. But if it helps, ok.

There would be two, one for Python and the other for running tests.

stevepiercy

@jensens I thought I had submitted it. Here ya go!

docs/developer-guide/deprecation.md

Co-authored-by: Jens W. Klein <[email protected]>

mauritsvanrees

Thanks for working on this. I added some suggestions.

docs/developer-guide/deprecation.md

mauritsvanrees · 2025-12-18T10:20:52Z

docs/developer-guide/deprecation.md

+
+### Zope
+
+Zope configures logging and warnings, so the steps as described below in {ref}`deprecation-warning-python-label` aren't needed.


We can drop the whole section Zope with plone.recipe.zopeinstance since this feature was dropped with WSGI server usage. So, it does not make sense to keep the Python subheading, right?

I think you mean we don't need to keep the Zope subheading. The Python subheading still seems accurate.

I must say I always get deprecation warnings when starting Plone though, even though I don't think I have configured anything to enable it. So when I don't want them, I explicitly disable them with export PYTHONWARNINGS=ignore. This may depend on how Python is installed, and with which flags it was built.

Shall we mention somehow this change in the developer guide or focus on the current state?

Indeed focus on current state, but if possible mention the change as Steve says.

docs/developer-guide/deprecation.md

Co-authored-by: Maurits van Rees <[email protected]>

stevepiercy

A couple of minor tweaks and the removal of the Zope section and revision of the parent heading content.

stevepiercy · 2025-12-20T09:04:52Z

docs/developer-guide/deprecation.md

+
+To enable deprecation warnings, use the `-W` command.
+
+Given you're using a modern buildout with a virtual environment as recommended, the command would be the following


Suggested change

Given you're using a modern buildout with a virtual environment as recommended, the command would be the following

Given you're using a modern buildout with a virtual environment as recommended, the command would be the following.

stevepiercy · 2025-12-20T09:06:35Z

docs/developer-guide/deprecation.md

+
+:   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 {ref}`-W[all|module|once]  <python:using-on-warnings>` argument.


Suggested change

Output can be enabled by starting the Python interpreter with the {ref}`-W[all|module|once] <python:using-on-warnings>` argument.

Output can be enabled by starting the Python interpreter with the {ref}`-W[all|module|once] <python:using-on-warnings>` argument.

stevepiercy · 2025-12-20T09:09:23Z

docs/developer-guide/deprecation.md

+
+## Enable deprecation warnings
+
+This section describes how to enable deprecation warnings in Zope, Python, and tests.


Suggested change

This section describes how to enable deprecation warnings in Zope, Python, and tests.

This section describes how to enable deprecation warnings in Python, both in an interpreter and code, and when running tests.

stevepiercy · 2025-12-20T09:09:44Z

docs/developer-guide/deprecation.md

+
+### Zope
+
+Zope configures logging and warnings, so the steps as described below in {ref}`deprecation-warning-python-label` aren't needed.


There would be two, one for Python and the other for running tests.

stevepiercy · 2025-12-20T09:10:16Z

docs/developer-guide/deprecation.md

+### Zope
+
+Zope configures logging and warnings, so the steps as described below in {ref}`deprecation-warning-python-label` aren't needed.
+
+Using `plone.recipe.zope2instance`, add the option `deprecation-warnings = on` to the buildout's `[instance]` section.
+
+```cfg
+[buildout]
+parts = instance
+
+[instance]
+recipe = plone.recipe.zope2instance
+# …
+deprecation-warnings = on
+# …
+```
+
+This adds the following line to the {file}`zope.conf` file.
+
+```cfg
+debug-mode on
+```
+
+Without the recipe, this can be set manually as well.
+In {file}`zope.conf`, define custom filters for warnings, such as the following example.
+
+```xml
+<warnfilter>
+    action always
+    category exceptions.DeprecationWarning
+</warnfilter>
+```


Per @mauritsvanrees's suggestion.

Suggested change

### Zope

Zope configures logging and warnings, so the steps as described below in {ref}`deprecation-warning-python-label` aren't needed.

Using `plone.recipe.zope2instance`, add the option `deprecation-warnings = on` to the buildout's `[instance]` section.

```cfg

[buildout]

parts = instance

[instance]

recipe = plone.recipe.zope2instance

# …

deprecation-warnings = on

# …

```

This adds the following line to the {file}`zope.conf` file.

```cfg

debug-mode on

```

Without the recipe, this can be set manually as well.

In {file}`zope.conf`, define custom filters for warnings, such as the following example.

```xml

<warnfilter>

action always

category exceptions.DeprecationWarning

</warnfilter>

```

add deprecation chapter

973020c

MrTango requested review from ale-rt and stevepiercy February 11, 2025 12:58

fix broken links in deprecation chapter

bd6eac9

MrTango mentioned this pull request Feb 11, 2025

Transfer Plone Deprecation Guide? #1464

Open

2 tasks

ale-rt reviewed Feb 11, 2025

View reviewed changes

MrTango and others added 12 commits February 11, 2025 16:01

Update docs/backend/deprecation.md

ff7461b

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

6027930

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

e6acc83

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

b909069

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

b0923fb

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

7ca4ede

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

66a58dc

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

c859367

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

4e32566

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

c7cad7a

Co-authored-by: Alessandro Pisa <[email protected]>

remove meta.zcml attribute from z3c.jbot include

a9fc020

Update docs/backend/deprecation.md

151aa67

Co-authored-by: Alessandro Pisa <[email protected]>

ale-rt reviewed Feb 11, 2025

View reviewed changes

docs/backend/deprecation.md Outdated Show resolved Hide resolved

docs/backend/deprecation.md Outdated Show resolved Hide resolved

docs/backend/deprecation.md Outdated Show resolved Hide resolved

ale-rt added 3 commits February 11, 2025 16:03

Fix ty

cff3ad6

Fix typo

d0286e4

Fix typo

1c733a3

ale-rt reviewed Feb 11, 2025

View reviewed changes

docs/backend/deprecation.md Outdated Show resolved Hide resolved

ale-rt reviewed Feb 11, 2025

View reviewed changes

docs/backend/deprecation.md Outdated Show resolved Hide resolved

ale-rt reviewed Feb 11, 2025

View reviewed changes

docs/backend/deprecation.md Outdated Show resolved Hide resolved

ale-rt reviewed Feb 11, 2025

View reviewed changes

docs/backend/deprecation.md Outdated Show resolved Hide resolved

ale-rt reviewed Feb 12, 2025

View reviewed changes

docs/backend/deprecation.md Outdated Show resolved Hide resolved

MrTango and others added 3 commits February 12, 2025 11:39

Update docs/backend/deprecation.md

49e96f8

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

8608dff

Co-authored-by: Alessandro Pisa <[email protected]>

Update docs/backend/deprecation.md

155c344

Co-authored-by: Alessandro Pisa <[email protected]>

split deprecation guide into two file according to diataxis principles

46b14eb

jensens force-pushed the chapter-deprecation branch from 2ccbcf2 to 46b14eb Compare December 4, 2025 23:58

ale-rt requested changes Dec 5, 2025

View reviewed changes

docs/developer-guide/deprecation.md Outdated Show resolved Hide resolved

Update docs/developer-guide/deprecation.md

ef52530

Co-authored-by: Alessandro Pisa <[email protected]>

ale-rt previously approved these changes Dec 5, 2025

View reviewed changes

stevepiercy added 2 commits December 9, 2025 03:21

Merge branch '6.0' into chapter-deprecation

25cb25b

- Fix English grammar and syntax

9bedd0e

- Generalize for npm and Volto - Clean up MyST style and formatting

stevepiercy dismissed ale-rt’s stale review via 9bedd0e December 9, 2025 12:17

Refine some grammar

78165e0

stevepiercy mentioned this pull request Dec 13, 2025

Add deprecation policy or guide to documentation plone/volto#7696

Open

- Add MyST syntax to link to Python objects, improve rendering

a1e40f4

- Clean up grammar, MyST syntax - Indent code within list items. - Use ruff style code example formatting.

stevepiercy requested changes Dec 14, 2025

View reviewed changes

Merge branch '6.0' into chapter-deprecation

f0e9b8c

stevepiercy reviewed Dec 15, 2025

View reviewed changes

jensens reviewed Dec 15, 2025

View reviewed changes

docs/developer-guide/deprecation.md Show resolved Hide resolved

stevepiercy and others added 2 commits December 15, 2025 15:52

Update docs/developer-guide/deprecation.md

6fa028f

Co-authored-by: Jens W. Klein <[email protected]>

Merge branch '6.0' into chapter-deprecation

0dd2608

mauritsvanrees requested changes Dec 18, 2025

View reviewed changes

jensens and others added 5 commits December 19, 2025 19:48

Update docs/developer-guide/deprecation.md

3dd2949

Co-authored-by: Maurits van Rees <[email protected]>

Update docs/developer-guide/deprecation.md

6a29889

Co-authored-by: Maurits van Rees <[email protected]>

Update docs/developer-guide/deprecation.md

0dab30b

Co-authored-by: Maurits van Rees <[email protected]>

Update docs/developer-guide/deprecation.md

b05efb9

Co-authored-by: Maurits van Rees <[email protected]>

Merge branch '6.0' into chapter-deprecation

397b9d9

stevepiercy requested changes Dec 20, 2025

View reviewed changes

stevepiercy requested review from ale-rt, jensens and mauritsvanrees December 20, 2025 09:12


		### Zope

		Zope configures logging and warnings, so the steps as described below in {ref}`deprecation-warning-python-label` aren't needed.


		To enable deprecation warnings, use the `-W` command.

		Given you're using a modern buildout with a virtual environment as recommended, the command would be the following


		: 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 {ref}`-W[all\|module\|once] <python:using-on-warnings>` argument.


		## Enable deprecation warnings

		This section describes how to enable deprecation warnings in Zope, Python, and tests.

Uh oh!

add deprecation chapter #1850

Are you sure you want to change the base?

add deprecation chapter #1850

Conversation

MrTango commented Feb 11, 2025 • edited by stevepiercy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

First-time contributors

Submit a pull request

Issue number

Description

Add screenshots or links to a preview of the changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jensens commented Dec 5, 2025

Uh oh!

Uh oh!

ale-rt left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

jensens commented Dec 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mauritsvanrees left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

MrTango commented Feb 11, 2025 •

edited by stevepiercy

Loading

ale-rt left a comment •

edited

Loading