docs: adding migration guide (#412)

doc/source/index.rst

@@ -2,6 +2,11 @@
    :start-after: .. readme_common_begins
    :end-before: .. readme_common_ends
 
+.. note:: Adapting to a new version?
+
+   If you are adapting to a new version of the actions, please refer to the
+   :ref:`migration guide <migration_guide>`.
+
 For more information on available actions and how to use them,
 see each card below:
 
@@ -69,3 +74,4 @@ see each card below:
    release-actions/index
    housekeeping-actions/index
    vulnerability-actions/index
+   migration_guide

doc/source/migration_guide.rst

@@ -0,0 +1,57 @@
+.. _migration_guide:
+
+Migration guide
+===============
+
+This guide provides information on new features, breaking changes, how to migrate
+from one version of the actions to another, and other upstream dependencies that
+have been updated.
+
+Version ``v5``
+--------------
+
+**New features:**
+
+- Added ``ansys/action/check-vulnerabilities`` to check for third party and first party vulnerabilities.
+  This action uses ``bandit`` and ``safety`` to check for vulnerabilities in the code and dependencies, respectively.
+- Added ``ansys/actions/docker-style`` to check for Dockerfile style issues using ``hadolint``.
+- Allow ``vale`` version input in ``ansys/actions/doc-style`` action. By default, ``2.29.6`` is used.
+- Allow using the twine ``--skip-existing`` flag in the ``ansys/actions/release-pypi-*`` actions.
+- Allow using the ``ansys/actions/doc-build`` action to build documentation using a dedicated requirements file (and
+  consequently, no need to have a Python project to use it).
+- Allow for independent documentation releases in case of patch release when using ``ansys/actions/doc-deploy-stable`` action.
+  This will create independent documentation versions for patch releases.
+
+**Breaking changes:**
+
+- Upgrade ``actions/upload-artifact`` and ``actions/download-artifact`` to version ``v4``.
+- Upgrade ``actions/setup-python`` to version ``v5``.
+
+**Migration steps:**
+
+- Since artifacts are uploaded/downloaded using the new ``actions/*-artifact``, artifact names cannot
+  be duplicated inside the workflow. Also, versions ``v3`` and ``v4`` are incompatible with each other. If you are using
+  version ``v3`` independently inside your workflow, you need to upgrade to version ``v4``.
+- The upgrade to ``actions/setup-python`` version ``v5`` is not mandatory, but it is recommended to use the latest version.
+  However, it has been seen that in Windows self-hosted runners, if a certain Python version is not already stored in the
+  cache, the action fails. This is a known issue and the workaround is to use the previous version of the action.
+
+**Dependency changes:**
+
+- Upgrade ``actions/checkout`` to version ``v4``.
+- Upgrade ``pypa/cibuildwheel`` to version ``v2.16.2``.
+- Upgrade ``peter-evans/create-or-update-comment`` to version ``v4``.
+- Upgrade ``vimtor/action-zip`` to version ``v1.2``.
+
+
+Version ``v4``
+--------------
+
+**Breaking Changes:**
+
+- Multi-version documentation deployment using ``ansys/actions/doc-deploy-stable`` and ``ansys/actions/doc-deploy-dev``.
+
+**Migration Steps:**
+
+- Visit `Multi-version migration from ansys/actions@v3 to ansys/actions@v4 <https://dev.docs.pyansys.com/how-to/documenting.html#multi-version-migration-from-ansys-actions-v3-to-ansys-actions-v4>`_
+  for a detailed migration guide.

requirements/requirements_doc.txt

@@ -1,6 +1,6 @@
 ansys-sphinx-theme==0.14.0
 pyyaml==6.0.1
-Sphinx==7.1.1
+Sphinx==7.2.6
 sphinx-copybutton==0.5.2
 sphinx-jinja==2.0.2
 sphinx_design==0.5.0