| .. _management_fixing_prev_mcumgr: |
| |
| Fixing and backporting fixes to Zephyr v2.7 MCUmgr |
| ################################################## |
| |
| The processes described in this document apply to both the zephyr repository itself and the MCUmgr :ref:`module <modules>` defined in :zephyr_file:`west.yml`. |
| |
| .. note:: |
| Currently, the backporting process, described in this document, is required only when providing |
| changes to Zephyr version 2.7 LTS |
| |
| There are two different processes: one for issues that have also been fixed in the current |
| version of Zephyr (backports), and one for issues that are being fixed only in a previous version. |
| |
| The upstream MCUmgr repository is located `in this page <https://github.com/apache/mynewt-mcumgr>`_. |
| The Zephyr fork used in version 2.7 and earlier is `located here <https://github.com/zephyrproject-rtos/mcumgr>`_. |
| Versions of Zephyr past 2.7 use the MCUmgr library that is `part of the Zephyr code base <https://github.com/zephyrproject-rtos/zephyr/tree/main/subsys/mgmt/mcumgr/lib>`_. |
| |
| Possible origins of a code change |
| ********************************* |
| |
| In Zephyr version 2.7 and earlier, you must first apply the fix |
| to the upstream repository of MCUmgr and then bring it to Zephyr with snapshot updates. |
| |
| As such, there are four possible ways to apply a change to the 2.7 branch: |
| |
| * The fix, done directly to the Zephyr held code of the MCUmgr library, is backported to the ``v2.7-branch``. |
| * The fix, ported to the Zephyr held code from the upstream repository, is backported to the ``v2.7-branch``. |
| * The fix, done upstream and no longer relevant to the current version, is directly backported |
| to the ``v2.7-branch``. |
| * The fix, not present upstream and not relevant for the current version of Zephyr, is |
| directly applied to the ``v2.7-branch``. |
| |
| The first three cases are cases of *backports* , the last one is a case of a *new fix* and has no |
| corresponding fix in the current version. |
| |
| .. _management_fixing_prev_mcumgr_submit: |
| |
| Applying fixes to previous versions of MCUmgr |
| ********************************************* |
| |
| This section indicates how to apply fixes to previous versions of MCUmgr. |
| |
| Creating a bug report |
| ===================== |
| |
| Every proposed fix requires a bug report submitted for the specified version of Zephyr affected by the bug. |
| |
| In case the reported bug in a previous version has already been fixed in the current version, the description |
| of the bug must be copied with the following: |
| |
| * Additional references to the bug in the current version |
| * The PR for the current version |
| * The SHAs of the commits, if the PR has already been merged |
| |
| You must also apply the ``backport v2.7-branch`` label to the bug report. |
| |
| Creating the pull request for the fix |
| ===================================== |
| |
| You can either create a *backport pull request* or a *new-fix pull request*. |
| |
| Creating backport pull requests |
| ------------------------------- |
| |
| Backporting a fix means that some or all of the fix commits, as they exist in the current version, |
| are ported to a previous version. |
| |
| .. note:: |
| Backporting requires the fix for the current version to be already merged. |
| |
| To create a backport pull request, do the following: |
| |
| 1. Port the fix commits from the current version to the previous version. |
| Even if some of the commits require changes, keep the commit messages of all the ported commits |
| as close to the ones in the original commits as possible, adding the following line: |
| |
| :: |
| |
| "Backporting commit <sha>" |
| |
| ``<sha>`` indicates the SHA of the commit after it has been already merged in the current version. |
| |
| #. Create the pull request selecting ``v2.7-branch`` as the merge target. |
| |
| #. Update ``west.yml`` within Zephyr, creating a pull-request to update the MCUmgr library referenced in |
| Zephyr 2.7. |
| |
| Creating new-fix pull requests |
| ------------------------------ |
| |
| When the fix needed does not have a corresponding fix in the current version, the bug report |
| must follow the ordinary process. |
| |
| 1. Create the pull request selecting ``v2.7-branch`` as the merge target. |
| |
| #. Update ``west.yml`` within Zephyr, creating a pull-request to update the MCUmgr library referenced in |
| Zephyr 2.7. |
| |
| Configuration management |
| ************************ |
| |
| This chapter describes the maintainers' side of accepting and merging fixes and backports. |
| |
| Prerequisites |
| ============= |
| |
| As a maintainer, these are the steps required before proceeding with the merge process: |
| |
| 1. Check if the author has followed the correct steps that are required to apply the fix, as described in |
| :ref:`management_fixing_prev_mcumgr_submit`. |
| |
| #. Ensure that the author of the fix has also provided the ``west.yml`` update for Zephyr 2.7. |
| |
| The specific merging process depends on where the fix comes from and whether it is a *backport* or a *new |
| fix*. |
| |
| Merging a backported fix |
| ======================== |
| |
| There are two possible sources of backports: |
| |
| * The Zephyr code base |
| * A direct fix from upstream |
| |
| Both cases are similar and differ only in the branch name. |
| |
| To merge a backported fix after the pull request for the fix has gone through the review process, |
| as a maintainer, do the following: |
| |
| 1. Create a branch named as follow: |
| |
| :: |
| |
| backport-<source>-<pr_num>-to_v2.7-branch |
| |
| ``<source>`` can be one of the following: |
| |
| * ``upstream`` - if the fix has originally been merged to the upstream repository. |
| * ``zephyr`` - if the fix has been applied to the Zephyr internal MCUmgr library (past 2.7 versions). |
| |
| ``<pr_num>`` is the number of the original pull request that has already been merged. |
| |
| For example, a branch named ``backport-upstream-137-to-v2.7-branch`` indicates a backport of pull |
| request 137, which has already been merged to the upstream repository of MCUmgr. |
| |
| #. Push the reviewed pull-request branch to the newly created branch and merge the backport branch |
| to ``v2.7-branch``. |
| |
| Merging a new fix |
| ================= |
| |
| Merging a new fix, that is not a backport of either any upstream or Zephyr fix, does not require any special |
| treatment. Apply the fix directly at the top of ``v2.7-branch``. |
| |
| Merge west.yml |
| ============== |
| |
| As an MCUmgr maintainer, you may not be able to merge the ``west.yml`` update, to introduce the fix to Zephyr. |
| However, you are responsible for such a merge to happen as soon as possible after the MCUmgr fixes have been |
| applied to the ``v2.7-branch`` of the MCUmgr. |