.. _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. Development version ------------------- **New features:** - Added an optional input to the ``ansys/actions/build-library`` action to disable library build validation on demand using the ``validate-build: false`` argument. This is useful when you want to skip the library build validation step in the action. - Incorporated the usage of `Trusted Publisher `_ in the ``ansys/actions/release-pypi-*`` actions. This is useful when you want to sign the package before uploading it to PyPI. **Breaking changes:** **Migration steps:** - To set up your repository to use the ``ansys/actions/release-pypi-*`` action with the `Trusted Publisher`_ approach, see the :ref:`release_pypi_trusted_publisher`. Version ``v6`` -------------- **New features:** - Added the ``ansys/actions/check-vulnerabilities`` action to check for third-party and first-party vulnerabilities. This is useful when you want to hide the vulnerabilities from the logs, but still want to fail the action if vulnerabilities are found. - Avoid creating issues by default if vulnerabilities are found in the ``ansys/actions/check-vulnerabilities`` action. - Create a changelog fragment file for each pull request using ``towncrier`` in the ``ansys/actions/doc-changelog`` action. - Generate a new section in ``CHANGELOG.md`` if fragment files exist using ``towncrier`` in the ``ansys/actions/doc-deploy-changelog`` action. By default, it updates the CHANGELOG in the release branch and creates a pull request into the main branch with the updated CHANGELOG and deleted fragment files. - SEO improvements. These are implemented inside the `doc-deploy-dev `_ and the `doc-deploy-stable `_. Users are not required to apply any changes to their ``conf.py`` or ``.github/workflows/*.yml`` files. Noticable changes include: - No more redirect from landing page to `version/stable/index.html` - Generation of ``robots.txt`` file for avoiding indexing old documentation versions - Generation of `sitemap.xml` file for quicker indexing of `version/stable/` pages - Inclusion of `canonical` link tags in all HTML files for SEO purposes - Extend ``ansys/actions/doc-build`` to be able to run in Windows runners. To buid the documentation in a Windows runner, we install ``Chocolatey`` and ``Miktex``. - Allow ``ansys/actions/commit-style`` to work with upper case in the type field of a commit. Expected types are upper cases of `conventional commit types `_. **Breaking changes:** - Upgrade default ``vale`` version from ``2.29.6`` to ``3.4.1`` in ``ansys/actions/doc-style`` action. - Vale configuration file ``.vale.ini`` and ``Vocab/ANSYS`` has to be changed. **Migration steps:** - To set up your repository to use the ``ansys/actions/doc-changelog`` action, see the :ref:`docs_changelog_action_setup`. - To set up your repository to use the ``ansys/actions/doc-deploy-changelog`` action, see the :ref:`docs_deploy_changelog_action_setup`. - To set up your repository to use the ``ansys/actions/doc-style`` action, see the :ref:`docs_style_vale_update`. Version ``v5`` -------------- **New features:** - Added ``ansys/action/check-vulnerabilities`` to verify third party and first party vulnerabilities. This action uses ``bandit`` and ``safety`` to detect vulnerabilities in the code and dependencies, respectively. - Added ``ansys/actions/docker-style`` to detect 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 `Enable multi-version documentation `_ for a detailed migration guide. .. toctree:: :hidden: :maxdepth: 3 docs-changelog-setup docs-deploy-changelog-setup docs-style-vale-version-update release-pypi-trusted-publisher