1.. _management_fixing_prev_mcumgr: 2 3Fixing and backporting fixes to Zephyr v2.7 MCUmgr 4################################################## 5 6The processes described in this document apply to both the zephyr repository itself and the MCUmgr :ref:`module <modules>` defined in :zephyr_file:`west.yml`. 7 8.. note:: 9 Currently, the backporting process, described in this document, is required only when providing 10 changes to Zephyr version 2.7 LTS 11 12There are two different processes: one for issues that have also been fixed in the current 13version of Zephyr (backports), and one for issues that are being fixed only in a previous version. 14 15The upstream MCUmgr repository is located `in this page <https://github.com/apache/mynewt-mcumgr>`_. 16The Zephyr fork used in version 2.7 and earlier is `located here <https://github.com/zephyrproject-rtos/mcumgr>`_. 17Versions 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>`_. 18 19Possible origins of a code change 20********************************* 21 22In Zephyr version 2.7 and earlier, you must first apply the fix 23to the upstream repository of MCUmgr and then bring it to Zephyr with snapshot updates. 24 25As such, there are four possible ways to apply a change to the 2.7 branch: 26 27 * The fix, done directly to the Zephyr held code of the MCUmgr library, is backported to the ``v2.7-branch``. 28 * The fix, ported to the Zephyr held code from the upstream repository, is backported to the ``v2.7-branch``. 29 * The fix, done upstream and no longer relevant to the current version, is directly backported 30 to the ``v2.7-branch``. 31 * The fix, not present upstream and not relevant for the current version of Zephyr, is 32 directly applied to the ``v2.7-branch``. 33 34The first three cases are cases of *backports* , the last one is a case of a *new fix* and has no 35corresponding fix in the current version. 36 37.. _management_fixing_prev_mcumgr_submit: 38 39Applying fixes to previous versions of MCUmgr 40********************************************* 41 42This section indicates how to apply fixes to previous versions of MCUmgr. 43 44Creating a bug report 45===================== 46 47Every proposed fix requires a bug report submitted for the specified version of Zephyr affected by the bug. 48 49In case the reported bug in a previous version has already been fixed in the current version, the description 50of the bug must be copied with the following: 51 52* Additional references to the bug in the current version 53* The PR for the current version 54* The SHAs of the commits, if the PR has already been merged 55 56You must also apply the ``backport v2.7-branch`` label to the bug report. 57 58Creating the pull request for the fix 59===================================== 60 61You can either create a *backport pull request* or a *new-fix pull request*. 62 63Creating backport pull requests 64------------------------------- 65 66Backporting a fix means that some or all of the fix commits, as they exist in the current version, 67are ported to a previous version. 68 69.. note:: 70 Backporting requires the fix for the current version to be already merged. 71 72To create a backport pull request, do the following: 73 741. Port the fix commits from the current version to the previous version. 75 Even if some of the commits require changes, keep the commit messages of all the ported commits 76 as close to the ones in the original commits as possible, adding the following line: 77 78:: 79 80 "Backporting commit <sha>" 81 82 ``<sha>`` indicates the SHA of the commit after it has been already merged in the current version. 83 84#. Create the pull request selecting ``v2.7-branch`` as the merge target. 85 86#. Update ``west.yml`` within Zephyr, creating a pull-request to update the MCUmgr library referenced in 87 Zephyr 2.7. 88 89Creating new-fix pull requests 90------------------------------ 91 92When the fix needed does not have a corresponding fix in the current version, the bug report 93must follow the ordinary process. 94 951. Create the pull request selecting ``v2.7-branch`` as the merge target. 96 97#. Update ``west.yml`` within Zephyr, creating a pull-request to update the MCUmgr library referenced in 98 Zephyr 2.7. 99 100Configuration management 101************************ 102 103This chapter describes the maintainers' side of accepting and merging fixes and backports. 104 105Prerequisites 106============= 107 108As a maintainer, these are the steps required before proceeding with the merge process: 109 1101. Check if the author has followed the correct steps that are required to apply the fix, as described in 111:ref:`management_fixing_prev_mcumgr_submit`. 112 113#. Ensure that the author of the fix has also provided the ``west.yml`` update for Zephyr 2.7. 114 115The specific merging process depends on where the fix comes from and whether it is a *backport* or a *new 116fix*. 117 118Merging a backported fix 119======================== 120 121There are two possible sources of backports: 122 123* The Zephyr code base 124* A direct fix from upstream 125 126Both cases are similar and differ only in the branch name. 127 128To merge a backported fix after the pull request for the fix has gone through the review process, 129as a maintainer, do the following: 130 1311. Create a branch named as follow: 132 133 :: 134 135 backport-<source>-<pr_num>-to_v2.7-branch 136 137 ``<source>`` can be one of the following: 138 139 * ``upstream`` - if the fix has originally been merged to the upstream repository. 140 * ``zephyr`` - if the fix has been applied to the Zephyr internal MCUmgr library (past 2.7 versions). 141 142 ``<pr_num>`` is the number of the original pull request that has already been merged. 143 144 For example, a branch named ``backport-upstream-137-to-v2.7-branch`` indicates a backport of pull 145 request 137, which has already been merged to the upstream repository of MCUmgr. 146 147#. Push the reviewed pull-request branch to the newly created branch and merge the backport branch 148 to ``v2.7-branch``. 149 150Merging a new fix 151================= 152 153Merging a new fix, that is not a backport of either any upstream or Zephyr fix, does not require any special 154treatment. Apply the fix directly at the top of ``v2.7-branch``. 155 156Merge west.yml 157============== 158 159As an MCUmgr maintainer, you may not be able to merge the ``west.yml`` update, to introduce the fix to Zephyr. 160However, you are responsible for such a merge to happen as soon as possible after the MCUmgr fixes have been 161applied to the ``v2.7-branch`` of the MCUmgr. 162
