diff --git a/doc/services/device_mgmt/index.rst b/doc/services/device_mgmt/index.rst index 09d5aeb4da9..535621c82d9 100644 --- a/doc/services/device_mgmt/index.rst +++ b/doc/services/device_mgmt/index.rst @@ -9,7 +9,6 @@ Device Management mcumgr.rst mcumgr_handlers.rst mcumgr_callbacks.rst - mcumgr_backporting.rst smp_protocol.rst smp_transport.rst dfu.rst diff --git a/doc/services/device_mgmt/mcumgr_backporting.rst b/doc/services/device_mgmt/mcumgr_backporting.rst deleted file mode 100644 index 58871874e79..00000000000 --- a/doc/services/device_mgmt/mcumgr_backporting.rst +++ /dev/null @@ -1,161 +0,0 @@ -.. _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 ` 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 `_. -The Zephyr fork used in version 2.7 and earlier is `located here `_. -Versions of Zephyr past 2.7 use the MCUmgr library that is `part of the Zephyr code base `_. - -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 " - - ```` 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---to_v2.7-branch - - ```` 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). - - ```` 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.