diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 28192374a..fd7aec48f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,7 +4,7 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.11.13 hooks: - - id: ruff + - id: ruff-check - id: ruff-format - repo: https://github.com/adamchainz/blacken-docs diff --git a/doc/source/how-to/deprecating.rst b/doc/source/how-to/deprecating.rst new file mode 100644 index 000000000..c50bf90c6 --- /dev/null +++ b/doc/source/how-to/deprecating.rst @@ -0,0 +1,139 @@ +.. _deprecating: + +Deprecating a library +===================== + +As time passes, some libraries may become outdated or replaced by better alternatives. +When this happens, it is important to deprecate the old library properly to ensure users +are aware of the change and can transition smoothly. + +For the PyAnsys ecosystem, follow this specific process for deprecating libraries. +This process helps maintain clarity and consistency across the projects. + +Maintainer tasks +---------------- + +If you are a maintainer of a library that is being deprecated, please follow these steps. As +an illustrative example, the deprecation of `PyAdditive Widgets `_ +is used in this guide. + +1. **Inform the PyAnsys Core team**: Before proceeding with the deprecation, it is essential to + inform the PyAnsys Core team. This can be done by sending an email to + the team at `pyansys.core@ansys.com `_. This step ensures that the + deprecation is communicated effectively and that the team can assist with any necessary + changes in the PyAnsys ecosystem. + +2. **Close all open issues and pull requests**: Before deprecating the library, ensure that all + open issues and pull requests in the library's repository are closed. This helps to avoid + confusion and ensures that users are aware that the library is no longer actively maintained. + You can close issues and pull requests with a comment explaining that the library is being + deprecated and is no longer be supported. + +3. **Create a deprecation issue**: Open an issue in the library's repository to announce the + deprecation. This issue should explain why the library is being deprecated, what alternatives + are available, and any relevant timelines. See a template below for the issue content. + + .. warning:: + + Make sure to adapt the template to your specific library and situation. + + .. code:: markdown + + ## ⚠️ Project Deprecation Notice + + **This repository is no longer maintained as of [DATE].** + + ### Reason for deprecation + [Explain briefly why the project is being deprecated — e.g. better alternatives, no time to maintain, outdated use case.] + + ### Alternatives + If you're looking for a maintained alternative, consider: + - [Alternative 1](https://...) + - [Alternative 2](https://...) + + ### What this means + - No further updates, bug fixes, or pull request reviews + - Issues will be closed + - The repository will be archived + + Thank you to everyone who contributed, used, or supported this project! + + This issue serves as a permanent record of the deprecation and provide users with + necessary information about alternatives. + + Make sure to pin the issue to the top of the repository so that it is easily visible to users. + This can be done by selecting the "Pin issue" option in the issue's right-side menu, on GitHub. + + See an example at `PyAdditive Widgets deprecation issue`_. + +4. **Adapt the README**: Update the library's ``README`` file to reflect the deprecation. + This should include a clear notice at the top of the ``README``, informing users that the + library is deprecated. See an example at `PyAdditive Widgets README`_. + +5. **(Optional) Add a warning in the code**: If applicable, add a warning in the code itself to inform users + that the library is deprecated. This can be done using Python's `warnings` module. For example: + + .. note:: + + Make sure to adapt the URL in the warning message. + + .. code:: python + + # At the top of your main module or package (i.e. src/ansys/<...>/__init__.py) + + import warnings + + warnings.warn( + "This library is deprecated and will no longer be maintained. " + "Please consider using alternatives. " + "For more information check https://github.com/ansys//issues/", + DeprecationWarning, + ) + + See an example at `PyAdditive Widgets deprecation warning`_. + +6. **(Optional) Adapt the documentation**: PyAnsys libraries host documentation in GitHub Pages through + the ``gh-pages`` branch. If your library has documentation, consider adding a deprecation notice + to the documentation as well. A similar note to the one in the ``README`` can be added at the landing + page of the documentation. If you main landing page is an ``.rst`` file, you can add the + deprecation notice as a note directive: + + .. code:: rst + + .. warning:: + + This library is deprecated and will no longer be maintained. Please consider using alternatives. + For more information, check the `deprecation issue `_. + +7. **(Optional) Make a last release**: If you carried out steps 5 and 6, consider making a final release + of the library that includes the deprecation warning. This ensures that users who install + the library in the future see the warning immediately. + +8. **Archive the repository**: Once the deprecation issue is created and the ``README`` is updated, + you can archive the repository. This prevents any further changes to the repository and + signals to users that the library is no longer maintained. To archive a repository, go to the + repository settings and select "Archive this repository." + +These steps ensure that the deprecation process is clear and transparent, allowing users to +transition smoothly to alternatives while maintaining the integrity of the PyAnsys ecosystem. + +.. note:: + + The deprecation process may vary slightly depending on the specific library and its + context. However, the core principles should remain consistent across all deprecations. + +Core team tasks +--------------- + +The PyAnsys Core team is responsible for assisting with the deprecation process by: + +- Reviewing the deprecation issue to ensure it meets the project's standards. +- Assisting with the above steps, if necessary. +- Remove from PyPI the configuration (PyPI token or trusted publisher) for the library. +- Archive the project on PyPI. See `PyAdditive Widgets PyPI archive`_. +- Removing the library from the `PyAnsys metapackage `_, automation project + and the ``pyansys-dev`` repository. See example pull requests: + + - `Metapackage deprecation PR`_ + - `PyAnsys Dev deprecation PR`_ + - `Automation project deprecation PR`_ diff --git a/doc/source/how-to/index.rst b/doc/source/how-to/index.rst index 4fcbbec5d..8b54ed6df 100644 --- a/doc/source/how-to/index.rst +++ b/doc/source/how-to/index.rst @@ -106,6 +106,12 @@ and app APIs. How to handle vulnerabilities in PyAnsys packages. + .. grid-item-card:: :fas:`fa-solid fa-bug` Deprecating a library + :link: deprecating + :link-type: doc + :padding: 2 2 2 2 + + How to deprecate a PyAnsys library. .. toctree:: :maxdepth: 3 @@ -125,3 +131,4 @@ and app APIs. dns-configuration compatibility vulnerabilities + deprecating diff --git a/doc/source/links.rst b/doc/source/links.rst index 862fb5ba3..cf72802e9 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -213,7 +213,7 @@ .. _PyPI API token: https://pypi.org/help/#apitoken .. #Vulnerabilities -.. _metapackage: https://github.com/pyansys/pyansys +.. _metapackage: https://github.com/ansys/pyansys .. _CVE: https://www.cve.org/ .. _Safety: https://pyup.io/safety/ .. _Bandit: https://bandit.readthedocs.io/en/latest/ @@ -221,3 +221,12 @@ .. _PyACP security considerations: https://acp.docs.pyansys.com/version/dev/user_guide/security_considerations.html .. _Github's documentation: https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability .. _PyAnsys Geometry subprocess advisory: https://github.com/ansys/pyansys-geometry/security/advisories/GHSA-38jr-29fh-w9vm + +.. #Deprecation +.. _PyAdditive Widgets README: https://github.com/ansys/pyadditive-widgets/blob/main/README.rst +.. _PyAdditive Widgets deprecation issue: https://github.com/ansys/pyadditive-widgets/issues/102 +.. _PyAdditive Widgets deprecation warning: https://github.com/ansys/pyadditive-widgets/blob/600915a8db2dbb02088266c17ba2be53584079d0/src/ansys/additive/widgets/__init__.py#L24-L31 +.. _PyAdditive Widgets PyPI archive: https://pypi.org/project/ansys-additive-widgets/ +.. _Metapackage deprecation PR: https://github.com/ansys/pyansys/pull/968 +.. _PyAnsys Dev deprecation PR: https://github.com/ansys-internal/pyansys-dev/pull/44 +.. _Automation project deprecation PR: https://github.com/ansys-internal/pyansys-maintenance-automation/pull/79