summaryrefslogtreecommitdiff
path: root/MAINTAINERS.md
diff options
context:
space:
mode:
authorBeniamino Galvani <bgalvani@redhat.com>2022-10-14 13:57:21 +0200
committerBeniamino Galvani <bgalvani@redhat.com>2022-10-17 09:53:15 +0200
commit2513503dc28bf34e436901dbe6cdcaad606437f9 (patch)
treecd500829c69c61fd1a0aec3e4db9afff3facb86f /MAINTAINERS.md
parentc280fe81aa6f205af139968e51c526d8ddd1714a (diff)
downloadNetworkManager-2513503dc28bf34e436901dbe6cdcaad606437f9.tar.gz
MAINTAINERS: improve documentation about backportsbg/backports-doc
- 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
Diffstat (limited to 'MAINTAINERS.md')
-rw-r--r--MAINTAINERS.md47
1 files 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.