1# Backporting {#backporting} 2 3In SPDK updating supported versions, other than the latest `master`, is carried out through 4a process called "backporting", which is owned by core maintainers and backporters (currently 5only Krzysztof Karaś). For such purposes, fixes to known issues or improvements to user experience, 6without introducing new functionality, are usually chosen. 7 8## How to backport to other SPDK maintained branches {#backporting_other_branches} 9 10Backporting process consists of two phases: 11 12### Selection 13 14`selection` may be done by anyone who knows about a patch that should be introduced to an older 15branch. A patch can be selected by adding a hashtag with desired destination release. This requires 16rights to change `Hashtags` field on a Gerrit patch, so its owner, core maintainers or 17somebody with Gerrit role `backporter` (currently only Krzysztof Karas `krzysztof.karas@intel.com`) 18will be able to add necessary tag. Patch 19[a4a0462](https://review.spdk.io/gerrit/c/spdk/spdk/+/17093) is a good example: `23.01` and `23.05` 20were added in the `Hashtags` field of this patch, indicating that it should be pushed to the 21corresponding branches `v23.01.x` and `v23.05.x`. 22 23### Preparation 24 25`preparation` may require some changes to the original code introduced by the patch, as it is taken 26from a newer version of the repository and uploaded on top of an older one. Patch 27[a4a0462](https://review.spdk.io/gerrit/c/spdk/spdk/+/17093) and its backport 28[62b467b](https://review.spdk.io/gerrit/c/spdk/spdk/+/18981) are a good example, 29because the code that they add is slightly different. 30Additionally, during `preparation` commit message must be changed: 31 32* footer should be stripped off of lines containing `Reviewed-by` and `Tested-by`, 33* `Reviewed-on` line should contain, in parentheses, name of the branch it was pulled from, 34* a line containing `(cherry picked from commit<original_commit_hash>)` should be added, 35* if the code was modified heavily, then the body of the message should match that. 36 37What should remain unchanged in commit message: 38 39* title of the patch, 40* `Change-Id`, 41* Signed-off-by of the original patch author. 42 43### Backporting script {#backporting_script} 44 45In SPDK there is a script automating above process to some degree. It is located in 46`scripts/backport.sh` and it requires users to have Gerrit username and SSH configuration, 47as it pulls lists of existing commits to compare states of `master` and target branch, to which 48backporting should be performed. The script will carry out most of commit message changes and try 49to apply code as is. If it ever encounters a merge conflict, it will stop and save backporting 50progress to a checkpoint file, from which user might resume after they are done fixing merge 51conflicts. 52 53## Updating submodules {#updating_submodules} 54 55SPDK uses forks of other repositories as submodules. This is done for two reasons: 56 57* to disable components that are unnecessary for SPDK to work, 58* to introduce bug fixes and resolve compatibility issues. 59 60The following example shows instructions on how DPDK would be updated from version 23.03 to 23.07, 61but updating other submodules should be done by analogy. 62 63### 1. Enter SPDK directory and update master branch 64 65```bash 66cd <path_to_spdk>; git checkout master; git pull 67``` 68 69### 2. Enter DPDK submodule directory and update it 70 71```bash 72cd <path_to_spdk>/dpdk; git checkout master; git pull 73``` 74 75### 3. Copy and checkout the latest fork 76 77```bash 78git branch -c spdk-23.07 spdk-23.07-copy; git checkout spdk-23.07-copy 79``` 80 81Modifying a copy of the fork, instead of working directly on it, will make it easier to go back 82in the future, if changes to the code are required later in the process. Otherwise, the branch 83would need to be reset and local progress would be lost. 84 85Notice that branches in submodules are named differently than SPDK branches. They usually consist 86of `spdk-` prefix followed by the version of submodule it corresponds to. In this case, for DPDK 8723.07 the branch is named `spdk-23.07`. 88 89### 4. Cherry-pick patches from previous submodule fork and verify them 90 91This requires browsing through [DPDK submodule repository](https://review.spdk.io/gerrit/q/project:spdk/dpdk) 92and verifying whether all patches from previous fork are necessary and if further changes should 93be introduced to ensure compatibility. In this case, patches from DPDK submodule branch 94`spdk-23.03` should be pulled and applied to `spdk-23.07`. At this point three scenarios 95are possible: 96 97* All patches are necessary and sufficient to make new version of the submodule compatible with 98 SPDK. 99* Some patches are unnecessary, because DPDK code has been changed and it matches SPDK needs, 100 so they can be skipped. 101* Patches from previous submodule fork are insufficient and further changes to the DPDK code are 102 required. That means either modifications to existing, pulled patches or creating new changes. 103 The latter might require debugging or manually checking dependencies. 104 105Patches for submodules should be pushed to appropriate branch: 106 107```bash 108git push https://review.spdk.io/gerrit/spdk/dpdk HEAD:refs/for/spdk-23.07 109``` 110 111Patches uploaded to Gerrit need to go through usual testing and review process before they are 112merged. Only after that the submodule update may be continued. Then, after the fork is ready, 113the submodule update may be carried out: 114 115```bash 116cd <path_to_spdk>; git checkout master; git pull 117cd <path_to_spdk>/dpdk; git checkout spdk-23.07; git pull 118cd ..; git add dpdk; git commit --signoff 119git push https://review.spdk.io/gerrit/spdk/spdk HEAD:refs/for/master 120``` 121 122Above commands update SPDK master branch, check out the newest fork of the DPDK submodule, then 123add it to a commit and finally push the submodule update to Gerrit. 124