Infineon · jaenrig-ifx · Aug 4, 2025 · Jul 22, 2025 · Jul 22, 2025 · Jul 22, 2025
diff --git a/README.md b/README.md
@@ -27,12 +27,12 @@ Please, [let us know](https://github.com/Infineon/arduino-devops/issues) if you
 
 You can get started by enabling the following workflows for your Arduino assets:
 
-* [Enable *compile-examples* build check for Arduino assets](tutorial)
-* [Enable *release* management for Arduino assets](tutorial-release)
+* [Enable *compile-examples* build check for Arduino assets](https://ifx-arduino-devops.readthedocs.io/en/latest/compile-examples/getting-started.html)
+* [Enable *release* management for Arduino assets](https://ifx-arduino-devops.readthedocs.io/en/latest/release/getting-started.html)
 
 ## More information
 
-Find the complete information in the repo [docs](docs/).
+Find the complete information in the repo [docs](https://ifx-arduino-devops.readthedocs.io/en/latest).
 
 ## Contributing
 

diff --git a/docs/compile-examples/getting-started.rst b/docs/compile-examples/getting-started.rst
@@ -12,7 +12,7 @@ Before you start, make sure you satisfy the following prerequisites:
 
 - Your Arduino asset (library or core) is hosted in a GitHub repository.
 - GitHub Actions is enabled in your repository. Check the `GitHub docs <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository>`_ to learn how to enable it.
-- If your asset is an Arduino core, first you need to `configure the repository <df>`_ to be able to generate the core package with the ``core-packager.py`` tool. 
+- If your asset is an Arduino core, first you need to :doc:`configure the repository <../scripts/arduino-packager>` to be able to generate the core package with the ``core-packager.py`` tool. 
 
 Enabling the reusable workflow
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/img/release-from-ga-select-version.png b/docs/img/release-from-ga-select-version.png
diff --git a/docs/img/release-from-ga-wflow.png b/docs/img/release-from-ga-wflow.png
diff --git a/docs/img/release-from-release-new-release.png b/docs/img/release-from-release-new-release.png
diff --git a/docs/img/release-from-release-tag.png b/docs/img/release-from-release-tag.png
diff --git a/docs/img/release-wflow-success.png b/docs/img/release-wflow-success.png
diff --git a/docs/overview/motivation.rst b/docs/overview/motivation.rst
@@ -11,12 +11,12 @@ Background
 
 The introduction of `arduino-cli <https://docs.arduino.cc/arduino-cli/>`_ has been a significant step forward in enabling programmatic handling of the Arduino toolchain and processes. This has opened up possibilities for automation via scripts and command line interfaces, making it easier to integrate tasks like build verification and testing into continuous integration servers.
 
-Current State and Objectives
+Current state and objectives
 ----------------------------
 
 While existing DevOps solutions, such as `compile-sketches action <https://github.com/arduino/compile-sketches>`_, provide some functionality, they do not fully meet our requirements. This project aims to fill this gap by providing a collection of utilities that solve specific DevOps use cases for managing Arduino assets. The scope of this project is intentionally open-ended, allowing it to evolve and adapt to emerging needs.
 
-Key Features and Design Principles
+Key features and design principles
 ----------------------------------
 
 The project's features are designed to be used via command line interface, making it easy to integrate with any non-GUI CI/CD framework and environment. Python is the language of choice, ensuring cross-platform compatibility. Although our primary development and testing platform is Linux, we strive to ensure platform independence.
@@ -25,7 +25,7 @@ When applicable, the features presented rely on the Arduino `platform <https://d
 
 The solutions provided for CI/CD are implemented through GitHub Actions `reusable workflows <https://docs.github.com/en/actions/sharing-automations/reusing-workflows>`_. This allows for easy deployment and upgrading of workflows with minimal effort. Given GitHub's popularity among Arduino developers, we have chosen to focus on GitHub Actions initially. However, we believe it should be straightforward to port the workflows to other CI/CD frameworks, such as GitLab, Jenkins, or Travis.
 
-Community Engagement and Contributions
+Community engagement and contributions
 --------------------------------------
 
 We believe these tools can be of general interest and applicability to any Arduino library or core developer. We encourage users to try them out, provide feedback, and contribute to making them more extensible and adaptable to various use cases.
diff --git a/docs/overview/usage.rst b/docs/overview/usage.rst
@@ -5,20 +5,20 @@ This repository is designed to automate DevOps processes for Arduino libraries a
 Thus, we recommend starting by adding the available `reusable workflows <https://github.com/Infineon/arduino-devops/tree/main/.github/workflows>`_ to your GitHub-hosted library or core.
 Before running the workflows, you'll need to configure them with some minimal settings.
 
-Step-by-Step Enablement
+Step-by-step enablement
 -----------------------
 
 To begin, we recommend following our Getting Started guides, which will walk you through the process of enabling the workflows:
 
 - :ref:`Getting started with compile-examples <compile_examples_getting_started>` workflow enablement. Learn how to set up the compile-examples workflow and start automating your build processes.
 - :ref:`Getting started with release <release_getting_started>` workflow enablement. Discover how to enable the release workflow and streamline your library or core releases.
 
-Advanced Customizations and Local Usage
+Advanced customizations and local usage
 ---------------------------------------
 
 As you become more familiar with the workflows and scripts, you might need advanced customizations to tailor them to your needs. You can also use the scripts locally on your development machine.
 
-Running Scripts Locally
+Running scripts locally
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 To run the scripts locally, first ensure you have the required dependencies installed (see :ref:`Requirements <requirements>`).

diff --git a/docs/release/description.rst b/docs/release/description.rst
@@ -0,0 +1,38 @@
+Description
+------------
+
+The ``release`` workflow provides an automated and standardized way to create releases for Arduino cores and libraries.
+It is designed to be used in CI/CD pipelines, enabling seamless integration with GitHub Actions to automate the entire release process.
+
+.. image:: ../img/release-wflow-success.png
+    :alt: Release workflow run success
+    :width: 60%
+    :align: center
+
+|
+
+The workflow integrates with the :doc:`arduino-release.py <../scripts/arduino-release>` script to handle semantic versioning, changelog generation, and GitHub release creation.
+It supports both Arduino cores and libraries, automatically detecting the asset type and applying the appropriate release procedures.
+
+The workflow is designed as a reusable GitHub Action that can be called from other repositories, providing a consistent release process across multiple Arduino assets.
+
+Implementation details
+^^^^^^^^^^^^^^^^^^^^^^
+
+From a high level, the GitHub Action workflow implements the following functionality:
+
+#. **Validate inputs** and determine the asset type (core or library).
+#. **Setup the environment** with required tools and dependencies using the provided setup script.
+#. **Execute the release process** using the arduino-release.py script with the specified version.
+#. **Create a GitHub release** with automatically generated changelog and release notes.
+#. **Upload release assets** including packaged cores or library archives.
+
+The workflow supports:
+
+- **Semantic versioning** with automatic version validation
+- **Changelog generation** from commit history and pull request information
+- **Multi-platform compatibility** for different operating systems
+- **Flexible setup scripts** to accommodate different project requirements
+- **Automatic asset packaging** for both cores and libraries
+
+Please explore the `release.yml <https://github.com/Infineon/arduino-devops/blob/main/.github/workflows/release.yml>`_ file to find out more about the implementation details of the reusable workflow.
diff --git a/docs/release/getting-started.rst b/docs/release/getting-started.rst
@@ -0,0 +1,204 @@
+.. _release_getting_started:
+
+Getting started
+----------------
+
+This section will guide you through the steps to setup the release workflow in your Arduino asset repository.
+
+Prerequisites
+^^^^^^^^^^^^^^
+
+Before you start, make sure you satisfy the following prerequisites:
+
+- Your Arduino asset (library or core) is hosted in a GitHub repository.
+- GitHub Actions is enabled in your repository. Check the `GitHub docs <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository>`_ to learn how to enable it.
+- You have appropriate permissions to create releases in your repository.
+- If your asset is an Arduino core, ensure it's properly configured for packaging with the :doc:`arduino-packager.py <../scripts/arduino-packager>` tool.
+
+Setting up the reusable workflow
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In your locally cloned repository, follow these steps:
+
+0. Create a new branch, for example ``devops/release-workflow``.
+
+    .. note::
+        This is not strictly necessary, but recommended to avoid pushing changes directly to the main branch.
+
+1. Create a new file in the ``.github/workflows`` directory, for example ``release.yml``.
+
+2. Add the following content to the file:
+
+    .. code:: yaml
+
+        name: Release
+
+        on:
+          push:
+            tags: 
+              - '[0-9]+.[0-9]+.[0-9]+**'
+          workflow_dispatch:
+            inputs:
+              version:
+                description: 'Release version'
+                required: true
+                default: ''
+                type: choice
+                options:
+                  - patch
+                  - minor
+                  - major
+
+        jobs:
+          arduino-devops:
+            uses: Infineon/arduino-devops/.github/workflows/release.yml@latest
+            with:
+              version: ${{ inputs.version }}
+            secrets: inherit
+
+    .. important::
+        Notice the ``@latest`` at the end of the ``uses`` line. This will use the latest version of the reusable workflow.
+        This is particularly useful to automatically get the latest updates in the reusable workflow.
+        Keep in mind that this may introduce breaking changes in case of major version updates.
+        You can also specify a specific version, for example ``@0.4.0``, or a branch, for example ``@main``.
+
+3. Commit your changes and push the branch to the remote.
+
+Additional workflow options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The GitHub Action reusable workflow provides some additional options often used in the release process:
+
+- ``setup-script``
+    Add a setup script that will be executed before building the release asset.
+    For example:
+
+    .. code:: yaml
+
+        jobs:
+          compile-examples:
+            uses: Infineon/arduino-devops/.github/workflows/compile-examples.yml@latest
+            with:
+              setup-script: bash scripts/before-core-build-setup.sh
+
+- ``release-ssh-key``
+    This is used to provide a secret SSH key from the repository secrets to the workflow.
+
+    For example:
+
+    .. code:: yaml
+
+        jobs:
+          arduino-devops:
+            uses: Infineon/arduino-devops/.github/workflows/release.yml@latest
+            with:
+              version: ${{ inputs.version }}
+            secrets:
+              release-ssh-key: ${{ secrets.release_wflow_key }}
+
+    This is required for Arduino libraries when using protection rules that prevent direct 
+    commit to the default branch.
+
+    As the workflow creates new commits and pushes them to the remote repository, the new 
+    commits will be rejected.
+
+    To avoid this, you can use the SSH key to push the changes to the remote repository.
+
+    Follow the steps to allow GitHub Actions to push changes directly to the default (protected) branch:
+
+        1. Add a new `deploy key <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys>`_ to your repository with write access.
+           This is available in the repository settings under "Deploy keys".
+        2. `Add the private key to your repository secrets <https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions>`_ with the name ``release_wflow_key``.
+        3. If you have any protection rules that prevent direct commits to the default branch, 
+           `enable the bypass option <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset>`_ for deploy keys.
+
+    More information about this approach in this `GitHub discussion <https://github.com/orgs/community/discussions/25305#discussioncomment-3247415>`_.
+
+Creating a release
+^^^^^^^^^^^^^^^^^^
+
+Once the workflow is set up, you can create releases in different ways:
+
+Release via GitHub actions 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Navigate to the ``Actions`` tab of your repository in GitHub.
+2. Select the ``Release`` workflow from the list.
+
+    .. image:: ../img/release-from-ga-wflow.png
+        :alt: Release workflow selection 
+        :width: 60%
+        :align: center
+
+    |
+
+3. Click ``Run workflow`` and select the default branch (usually ``main`` or ``master``) and the version increment: major, minor, or patch.
+
+    .. image:: ../img/release-from-ga-select-version.png
+        :alt: Release workflow select version 
+        :width: 50%
+        :align: center
+
+    |
+
+4. The workflow will automatically:
+
+   - Validate the version format
+   - Generate a changelog
+   - Create a GitHub release
+   - Upload release assets
+
+5. Once the workflow completes, you will see all the release steps passing, and the new release will be available in the ``Releases`` section of your repository.
+
+Release via GitHub release section
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Navigate to the ``Releases`` section of your repository.
+
+    .. image:: ../img/release-from-release-new-release.png
+        :alt: Release from release section
+        :width: 80%
+        :align: center
+
+    |
+
+2. Click on the ``Draft a new release`` button.
+
+    .. image:: ../img/release-from-release-tag.png
+        :alt: Set new tag manually
+        :width: 60%
+        :align: center
+
+    |
+
+3. Fill in the release tag (e.g., ``0.9.0``), and click on ``Create new tag: 0.9.0``. 
+
+    .. warning::
+        You are going to set the tag manually. It should be a valid semantic version (semver) format, with a valid increment.
+
+4. This will trigger the release workflow, and it will automatically:
+
+   - Validate the version format
+   - Generate a changelog
+   - Create a GitHub release
+   - Upload release assets
+
+5. Once the workflow completes, the new release will be updated with the corresponding title, changelog and assets.
+
+Release from local push
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In your local repository, use the ``arduino-script.py`` to create a new release. Assuming that you are in the root path of your repository, and that the script is located in the ``arduino-devops`` directory:
+
+  .. code:: bash
+
+    python arduino-devops/arduino-script.py new <version>
+
+This will automatically modify the required files, create a new tag, and push the changes to the remote repository.
+The release workflow will be triggered, verifying the version and creating the release.
+Check the ``release`` section of your repository to see the new release.
+
+  .. warning::
+    In case of an Arduino library, make sure that you have the necessary permissions to push modifications directly to the default (usually ``main`` or ``master``) branch of the repository.
+    The script will not only create a tag, but also update the `library.properties` file with the new version and push the changes to the remote repository.
+    The remote will reject the push if you do not have the right permissions. 
diff --git a/docs/release/index.rst b/docs/release/index.rst
@@ -1,16 +1,11 @@
 Release
-=======
+-------
 
-Description
------------
+This section contains documentation for the release workflow and related scripts.
 
-.. _release_getting_started:
+.. toctree::
+   :maxdepth: 2
 
-Getting started
-----------------
-
-Usage
------
-
-Asset creation
---------------
+   description
+   getting-started
+