Move setup.py metadata to pyproject.toml

docs/sources/how-to/index.md

@@ -45,6 +45,13 @@ Set up CI jobs, Python version matrices, OS dependencies, and environment variab
 Set up CI pipelines for GitLab-hosted repositories, including custom Docker images and OS dependencies.
 :::
 
+:::{grid-item-card} Convert `setup.py` metadata to `pyproject.toml`
+:link: setup-to-pyproject
+:link-type: doc
+
+Convert the metadata in `setup.py` to `pyproject.toml`
+:::
+
 :::{grid-item-card} Re-enable GitHub Actions
 :link: re-enable-actions
 :link-type: doc

docs/sources/how-to/setup-to-pyproject.md

@@ -0,0 +1,71 @@
+# Convert setup.py metadata to pyproject.toml
+
+`pyproject.toml`'s `[project]` metadata is the standard place to find a project metadata.
+
+Historically this was on `setup.py`, but it had plenty of problems.
+
+Now, you can write all of a project's metadata in `pyproject.toml`,
+[see the specification](https://packaging.python.org/en/latest/specifications/pyproject-toml/).
+
+All plone and collective python distributions are using `setup.py` to keep each project's metadata.
+
+[`zope.meta`](https://pypi.org/project/zope.meta) created a script to move the metadata from `setup.py` to `pyproject.toml`.
+
+In `plone.meta` this script from `zope.meta` has been adapted to suit the needs of the Plone ecosystem.
+
+## Conversion
+
+To convert the metadata do the following:
+
+```bash
+cd $REPOSITORY
+uvx --from plone.meta setup-to-pyproject .
+```
+
+i.e. go to your repository and run the `setup-to-pyproject` script from `plone.meta`.
+
+This will automatically create a commit on your repository with the changes.
+
+:::{note}
+Please review them carefully to ensure that the conversion was done properly.
+:::
+
+Ideally `setup.py` should look like this:
+
+```python
+from setuptools import setup
+
+# See pyproject.toml for package metadata
+setup()
+```
+
+### Issues link
+
+`setup-to-pyproject` accepts an optional argument: `--issues`.
+
+This option is to customize the issues link displayed on PyPI related to the project.
+
+It accepts the following options:
+
+- `own`: use the repository itself as the issue tracker
+- _URL_: provide a custom URL that will be used verbatim
+- _None_: if no value is provided `Products.CMFPlone` issue tracker is used
+
+## Clean up
+
+Run some tooling `tox run -e test` to ensure that the conversion worked.
+
+:::{note}
+It might be that the license field in `project.license` within `pyproject.toml` is broken.
+
+Please have a look at valid [license expressions](https://packaging.python.org/en/latest/specifications/license-expression/) to solve it.
+:::
+
+Re-configure the repository with `plone.meta` to ensure that the project metadata is kept:
+
+```bash
+cd $REPOSITORY
+uvx --from plone.meta config-package branch=current .
+```
+
+Make sure to review the commit generated by `config-package`.

news/315.feature

@@ -0,0 +1 @@
+Add `setup-to-pyproject` script to move `setup.py` metadata into `pyproject.toml` @gforcada

pyproject.toml

@@ -58,6 +58,7 @@ config-package = "plone.meta.config_package:main"
 multi-call = "plone.meta.multi_call:main"
 re-enable-actions = "plone.meta.re_enable_actions:main"
 switch-to-pep420 = "plone.meta.pep_420:main"
+setup-to-pyproject = "plone.meta.setup_to_pyproject:main"
 
 [tool.towncrier]
 directory = "news/"
@@ -119,4 +120,5 @@ omit = [
     "src/plone/meta/re_enable_actions.py",
     "src/plone/meta/pep_420.py",
     "src/plone/meta/multi_call.py",
+    "src/plone/meta/setup_to_pyproject.py",
     ]