From 92f205e54bca14d70d428fd7e5fd2f4fe596d57c Mon Sep 17 00:00:00 2001
From: Kynan Ware <47394200+BagToad@users.noreply.github.com>
Date: Tue, 24 Mar 2026 21:15:39 -0600
Subject: [PATCH] docs(featuredetection): document GHES removal criteria for
 ApiActorsSupported

Expand the ApiActorsSupported doc comment to explain the two API
generations (legacy AssignableUser vs actor-based AssignableActor),
what each returns, and the specific GraphQL schema additions to
check for when evaluating GHES support.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../featuredetection/feature_detection.go     | 28 +++++++++++++++----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/internal/featuredetection/feature_detection.go b/internal/featuredetection/feature_detection.go
index f0759bd3e..d4ef62070 100644
--- a/internal/featuredetection/feature_detection.go
+++ b/internal/featuredetection/feature_detection.go
@@ -24,11 +24,29 @@ type Detector interface {
 
 type IssueFeatures struct {
 	// TODO ApiActorsSupported
-	// ApiActorsSupported indicates the host supports actor-based APIs
-	// (replaceActorsForAssignable, requestReviewsByLogin, suggestedAssignableActors, etc.).
-	// True for github.com and ghe.com. False for GHES.
-	// Remove this flag once GHES supports these mutations, then collapse all
-	// // TODO ApiActorsSupported sites to the actor-only path.
+	// ApiActorsSupported indicates the host supports actor-based APIs. True for
+	// github.com and ghe.com, false for GHES.
+	//
+	// The GitHub API has two generations of assignee/reviewer types:
+	//
+	// Legacy (GHES): Uses AssignableUser (users only) and node-ID-based mutations.
+	//   - assignableUsers query returns []AssignableUser
+	//   - Mutations take node IDs (assigneeIds, userReviewerIds, teamReviewerIds)
+	//
+	// Actor-based (github.com): Uses AssignableActor (User + Bot union) and
+	// login-based mutations, enabling assignment of non-user actors like Copilot.
+	//   - suggestedActors query returns []AssignableActor (User | Bot)
+	//   - suggestedReviewerActors returns []ReviewerCandidate (User | Bot | Team)
+	//   - Mutations take logins (replaceActorsForAssignable, requestReviewsByLogin)
+	//
+	// When GHES adds support for the actor-based types and mutations, this flag
+	// can be removed and all // TODO ApiActorsSupported sites collapsed to the
+	// actor-only path. To verify GHES support, check whether the GHES GraphQL
+	// schema includes:
+	//   - The suggestedActors field on Repository (assignee search)
+	//   - The suggestedReviewerActors field on PullRequest (reviewer search)
+	//   - The replaceActorsForAssignable mutation
+	//   - The requestReviewsByLogin mutation
 	ApiActorsSupported bool
 }