From 0831777729edc6dd91cda70c9533c782b729b082 Mon Sep 17 00:00:00 2001
From: Rhys Arkins <rhys@arkins.net>
Date: Fri, 30 Aug 2024 19:05:18 +0200
Subject: [PATCH] docs(gomod): clarify major updates limitations (#31119)

---
 lib/modules/manager/gomod/readme.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/lib/modules/manager/gomod/readme.md b/lib/modules/manager/gomod/readme.md
index dd51f8c3cb..34dc5df94f 100644
--- a/lib/modules/manager/gomod/readme.md
+++ b/lib/modules/manager/gomod/readme.md
@@ -48,3 +48,14 @@ Rules from this list are converted to environment variable directives if they ma
 - No `hostType` is defined, or
 - `hostType` is `go`, or
 - `hostType` is a platform (`github`, `gitlab`, `azure`, etc.)
+
+### Major upgrades of dependencies
+
+Major upgrades in Go are different from most other ecosystems, because both the version and module name need to be changed.
+It is very common that such upgrades require changes to application code, which Renovate doesn't do.
+
+By default, Renovate will make such change in the `go.mod` files but nothing else - the rest is up to you.
+If you add `gomodUpdateImportPaths` to `postUpdateOptions` then Renovate will also use a third-party tool to migrate import paths within application code, but there may still be actual application logic which needs to be changed too.
+
+Ultimately: it is known and unavoidable that the majority of major Go upgrades won't be immediately mergeable.
+You might prefer to configure such major updates with `dependencyDashboardApproval=true` so that you can request them on demand, on supported platforms.
-- 
GitLab