From 2513503dc28bf34e436901dbe6cdcaad606437f9 Mon Sep 17 00:00:00 2001 From: Beniamino Galvani Date: Fri, 14 Oct 2022 13:57:21 +0200 Subject: MAINTAINERS: improve documentation about backports - clarify 'later branch' - remove backticks from commit hashes so that they are displayed as a link in gitlab - expand the section about backporting API https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1429 --- MAINTAINERS.md | 47 +++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 1c933ccaaa..f6bb39ecc4 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -4,15 +4,15 @@ Upstream backports There are situations where it is necessary to backport a patch to an earlier version of NetworkManager. -In order to do the backport, use `git cherry-pick -x`. Please use the commit -from the later branch. If the commit is not on that branch then it is also +In order to do the backport, use `git cherry-pick -x`. Please use the commit +from the next stable branch. If the commit is not on that branch then it is also necessary to backport to that branch. Example: -We want to backport commit `323e18276894591712a5e29f6e907562c79c5216` from -`main` (1.33) branch to `nm-1-30` branch. In order to do that, we must search -if this bug has been backported to 1.32. +We want to backport commit 323e18276894591712a5e29f6e907562c79c5216 from `main` +(1.33) branch to `nm-1-30` branch. In order to do that, we must search if this +bug has been backported to 1.32. `git log --all --grep "323e18276894591712a5e29f6e907562c79c5216"` @@ -38,7 +38,7 @@ Date: Wed Sep 1 09:30:29 2021 +0200 ``` In this case, the commit that should be backported is -`c94b1c43d4b5c5b88d67d7966d23a005028e78d8`. +c94b1c43d4b5c5b88d67d7966d23a005028e78d8. ### Resolving conflicts @@ -52,15 +52,26 @@ unnecessary changes or excesive code changes which is not common. ### Backporting API -NetworkManager allow the users to build their application against latest stable -release and then run it against a newer release without relinking. If we want -to backport a new API from main (1.33) to nm-1-30, we need to do something -similar to `57c1982867609bf759fce202a172ceeb51a21d5f` in main and nm-1-32 -branch. - -Example: - -An user wants to backport `05f2a0b0247ee4aa3da371658f310bc655cbf1af` from main -branch to `nm-1-30` branch. In this case, the user will need to write -`ec8df200f682c6726c1da624b5ae3984c4991056` and -`af00e39dd24644b8c979258e5579b43b88364d2f`. +NetworkManager allows the users to build their application against the latest +stable release and then run it against a newer release without relinking. To +allow this, we need to guarantee that after we release a version that includes a +new libnm linker version, then any release done after that point with a higher +version number contains that linker version with the same symbols. + +In practice when we want to backport new API from main we have two options: + +- if the new API hasn't been included in a stable release of NetworkManager, + then we can just backport the API to the old branch and pretend it was + introduced there. For example, 8763e6da9c5adb3c4ccf3b2713dbcc25a91c5ede + introduces new API on main during the 1.21 development cycle; 1.22 is not + released yet. Then the symbol is backported to nm-1-20 before 1.20.6 with + commit 90671a30b771d418953bd021d50c3cc43f253e6e. The symbol on main branch is + then adjusted with 551fd3e28f6b142bd57eefacfaf96b8fb8e309dd. Note that at this + point 1.20.6 must be released before 1.22.0. + +- if the new API is already included in a stable release, we backport the API to + the old branch and then duplicate the symbol on main with both versions. For + example, 2e2ff6f27aa1bfa7a27d49980b319873240ec84b introduces new API on main, + which is released as 1.12.0. The API is backported to 1.10.14 in commit + 19d7e66099ee43f47d6be0e740dc710fc365d200. Then, on main we add duplicate + symbols with commit 5eade4da11ee38a0e7faf4a87b2c2b5af07c5eeb. -- cgit v1.2.1