doc: add section on unexpected systemd UpheldBy behavior

See: systemd/systemd#35636

README.md

@@ -283,6 +283,29 @@ deprecated once the option is stable.
 
 ### Known Issues
 
+#### Manually stopping containers with UpheldBy
+
+systemd does not differentiate between a manual unit stop and a unit stopped due
+to a failure (i.e., in failed state). This means that if you stop a unit, it
+will automatically be started by the service(s) it depends on.
+
+Suppose you have the following Compose file:
+
+```yaml
+services:
+  app:
+    image: myname/app
+    depends_on:
+      - db
+  db:
+    image: postgres
+```
+
+If you *manually stop* the `app` systemd unit, the `db` unit will
+**automatically* restart it due to the `UpheldBy` setting.
+
+Discussion with the systemd team: https://github.com/systemd/systemd/issues/35636
+
 #### Docker & multiple networks
 
 If you are using the Docker runtime and a Compose service connects to multiple networks, you'll need to use v25+. Otherwise, the container service will fail to start.

compose.go

@@ -687,8 +687,10 @@ func (g *Generator) buildNixContainer(service types.ServiceConfig, networkMap ma
 		c.SystemdConfig.Unit.WantedBy = append(c.SystemdConfig.Unit.WantedBy, fmt.Sprintf("%s.target", rootTarget(g.Runtime, g.Project)))
 	}
 
-	// UpheldBy is only supported in NixOS 24.05+, which is why we have this
+	// Unfortunately, UpheldBy does not work as expected, so we're keeping it
 	// behind a flag.
+	//
+	// Refer to the "Known Issues" section in the README for details.
 	if g.UseUpheldBy {
 		// Set UpheldBy for this service's dependencies. This ensures that, when
 		// the dependency comes up, this container will also be started - and