Part 1
요약·해설
Bug report label, commit provenance, branch naming, west.yml snapshot update와 maintainer 책임을 단계별로 설명합니다.
Zephyr 2.7 LTS
v2.7-branch
west.yml
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
312F9F5A94F4EB52150F97D8AAB87525BAFBFA8F9633AE196760D6A400B088D6
.. _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>`_.
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.
Part 3
한국어 전문 번역
이 문서의 process는 Zephyr repository 자체와 west.yml에 정의된 MCUmgr module 모두에 적용됩니다.
Process는 두 종류입니다. 하나는 현재 Zephyr version에도 이미 fix가 있고 이를 옛 version으로 옮기는 backport이고, 다른 하나는 이전 version에서만 issue를 고치는 new fix입니다.
Upstream MCUmgr repository는 apache/mynewt-mcumgr입니다. Zephyr 2.7 이하에서 쓰는 fork는 zephyrproject-rtos/mcumgr이며, 2.7 이후 Zephyr는 Zephyr code base 안의 MCUmgr library를 사용합니다.
Code change가 생기는 경로
Zephyr 2.7 이하에서는 먼저 upstream MCUmgr repository에 fix를 적용한 다음 snapshot update로 Zephyr에 가져와야 합니다.
2.7 branch에 change를 적용하는 경로는 네 가지입니다.
- Zephyr가 보유한 MCUmgr library code에 직접 만든 fix를
v2.7-branch로 backport합니다. - Upstream repository에서 Zephyr 보유 code로 port한 fix를
v2.7-branch로 backport합니다. - Upstream에 적용됐지만 현재 version에는 더 이상 관련 없는 fix를
v2.7-branch로 직접 backport합니다. - Upstream에 없고 현재 Zephyr version에도 관련 없는 fix를
v2.7-branch에 직접 적용합니다.
앞의 세 경우는 backport이고 마지막 경우는 current version에 대응 fix가 없는 new fix입니다.
이전 MCUmgr version에 fix 적용
다음 절차로 이전 MCUmgr version에 fix를 적용합니다.
Bug report 작성
제안하는 모든 fix에는 bug가 영향을 주는 Zephyr version을 명시한 bug report가 필요합니다.
이전 version에서 보고한 bug가 current version에서 이미 고쳐졌다면 bug description에 다음 정보를 복사해 추가합니다.
- Current version bug에 대한 추가 reference
- Current version용 PR
- PR이 merge됐다면 commit SHA
Bug report에 backport v2.7-branch label도 적용해야 합니다.
Fix pull request 작성
Backport pull request 또는 new-fix pull request를 만들 수 있습니다.
Backport pull request 작성
Backport는 current version에 존재하는 fix commit 일부 또는 전체를 이전 version으로 port하는 작업입니다.
- Current version의 fix commit을 이전 version으로 port합니다. Commit 일부를 수정해야 하더라도 message는 original commit에 최대한 가깝게 유지하고 다음 line을 추가합니다.
"Backporting commit <sha>" ``<sha>`` indicates the SHA of the commit after it has been already merged in the current version.<sha>는 current version에 merge된 뒤의 commit SHA입니다. - Merge target을
v2.7-branch로 선택해 pull request를 만듭니다. - Zephyr의
west.yml을 갱신하고 Zephyr 2.7이 참조하는 MCUmgr library를 update하는 pull request를 만듭니다.
New-fix pull request 작성
필요한 fix에 current version의 대응 fix가 없다면 bug report는 일반 절차를 따릅니다.
- Merge target을
v2.7-branch로 선택해 pull request를 만듭니다. - Zephyr의
west.yml을 갱신하고 Zephyr 2.7이 참조하는 MCUmgr library를 update하는 pull request를 만듭니다.
Configuration management
이 절은 maintainer가 fix와 backport를 accept하고 merge하는 과정을 설명합니다.
선행 조건
Maintainer는 merge 전에 다음을 확인합니다.
- Author가 이전 MCUmgr version에 fix를 적용하는 올바른 절차를 따랐는지 확인합니다.
- Author가 Zephyr 2.7용
west.ymlupdate도 제공했는지 확인합니다.
구체적인 merge process는 fix 출처와 backport인지 new fix인지에 따라 달라집니다.
Backport fix merge
Backport source는 Zephyr code base 또는 upstream direct fix 두 가지이며, 두 경우는 branch name만 다르고 절차는 비슷합니다.
Fix pull request review가 끝나면 maintainer는 다음 작업을 수행합니다.
- 다음 형식으로 branch를 만듭니다.
backport-<source>-<pr_num>-to_v2.7-branch<source>는 upstream repository에서 merge된 fix이면upstream, Zephyr 내부 MCUmgr library에 적용된 fix이면zephyr입니다.<pr_num>은 이미 merge된 original pull request number입니다. 예를 들어backport-upstream-137-to-v2.7-branch는 upstream MCUmgr PR 137을 backport한다는 뜻입니다. - Review된 pull-request branch를 새 branch에 push하고 backport branch를
v2.7-branch에 merge합니다.
New fix merge
Upstream이나 Zephyr fix의 backport가 아닌 new fix는 특별한 처리가 필요하지 않습니다. v2.7-branch의 top에 직접 적용합니다.
west.yml merge
MCUmgr maintainer가 fix를 Zephyr에 도입하는 west.yml update를 직접 merge할 권한이 없을 수 있습니다. 그래도 MCUmgr fix가 MCUmgr v2.7-branch에 적용된 직후 가능한 한 빨리 그 update가 merge되도록 할 책임이 있습니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.