From 791bc4196e5c79f20a12f63ea0dce5f1b87752ba Mon Sep 17 00:00:00 2001
From: Solaris-star <820622658@qq.com>
Date: Tue, 21 Jul 2026 18:24:59 +0800
Subject: [PATCH] docs: clarify Upgrade blocks until child responds

The previous one-liner ("triggers an upgrade") reads like a fire-and-forget
call. Upgrade waits on the child response channel and returns an error if
the child fails or the process is already terminating/upgraded.

Fixes #81
---
 upgrader.go | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/upgrader.go b/upgrader.go
index 59e0afe..3179218 100644
--- a/upgrader.go
+++ b/upgrader.go
@@ -178,7 +178,13 @@ func (u *Upgrader) HasParent() bool {
 	return u.parent != nil
 }
 
-// Upgrade triggers an upgrade.
+// Upgrade starts a zero-downtime upgrade of the current process.
+//
+// It does not return immediately after spawning the child: the call blocks
+// until the upgrade either succeeds or fails. On failure it returns an error
+// (for example if the child exits uncleanly or the process is already
+// upgrading/terminating). On success the parent should drain work and exit
+// so the child can take over.
 func (u *Upgrader) Upgrade() error {
 	response := make(chan error, 1)
 	select {