submit: Add spice.submit.reviewers.addWhen config option

Add a new configuration option to control when configured reviewers
are added to change requests.

When set to "ready", reviewers configured via spice.submit.reviewers
are skipped for draft CRs. Reviewers specified via the --reviewer flag
are always added regardless of this setting.

Accepted values:
- "always" (default): add configured reviewers to all CRs
- "ready": only add configured reviewers when the CR is not a draft

Fixes #968

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: abhinav

.changes/unreleased/Added-20260201-181001.yaml

@@ -0,0 +1,6 @@
+kind: Added
+body: >-
+  submit: Add `spice.submit.reviewers.addWhen` configuration option,
+  which allows controlling whether reviewers configured with
+  `spice.submit.reviewers` are added to draft change requests.
+time: 2026-02-01T18:10:01.526545-08:00

doc/src/cli/config.md

@@ -363,9 +363,24 @@ The value must be a comma-separated list of reviewers.
 For GitHub, use usernames for individual reviewers
 or `org/team` format for team reviewers.
 
-Reviewers specified with the `--reviewers` flag
+Reviewers specified with the `--reviewer` flag
 will be combined with the configured reviewers.
 
+### spice.submit.reviewers.addWhen
+
+<!-- gs:version unreleased -->
+
+Controls when $$spice.submit.reviewers|configured reviewers$$
+are added to change requests.
+
+When set to `ready`, configured reviewers are skipped for draft CRs,
+except when added explicitly via the `--reviewer` flag.
+
+**Accepted values:**
+
+- `always` (default): add configured reviewers to all CRs
+- `ready`: only add configured reviewers when the CR is not a draft
+
 ### spice.submit.listTemplatesTimeout
 
 <!-- gs:version v0.8.0 -->

internal/handler/submit/handler.go

@@ -160,8 +160,9 @@ type Options struct {
 	Labels           []string `name:"label" short:"l" help:"Add labels to the change request. Pass multiple times or separate with commas."`
 	ConfiguredLabels []string `name:"configured-labels" help:"Default labels to add to change requests." hidden:"" config:"submit.label"` // merged with Labels
 
-	Reviewers           []string `short:"r" name:"reviewer" help:"Add reviewers to the change request. Pass multiple times or separate with commas." released:"v0.21.0"`
-	ConfiguredReviewers []string `name:"configured-reviewers" help:"Default reviewers to add to change requests." hidden:"" config:"submit.reviewers" released:"v0.21.0"` // merged with Reviewers
+	Reviewers           []string         `short:"r" name:"reviewer" help:"Add reviewers to the change request. Pass multiple times or separate with commas." released:"v0.21.0"`
+	ConfiguredReviewers []string         `name:"configured-reviewers" help:"Default reviewers to add to change requests." hidden:"" config:"submit.reviewers" released:"v0.21.0"`
+	ReviewersAddWhen    ReviewersAddWhen `name:"reviewers-add-when" help:"When to add configured reviewers." hidden:"" config:"submit.reviewers.addWhen" default:"always" released:"unreleased"`
 
 	Assignees           []string `short:"a" name:"assign" placeholder:"ASSIGNEE" help:"Assign the change request to these users. Pass multiple times or separate with commas." released:"v0.21.0"`
 	ConfiguredAssignees []string `name:"configured-assignees" help:"Default assignees to add to change requests." hidden:"" config:"submit.assignees" released:"v0.21.0"` // merged with Assignees
@@ -181,10 +182,24 @@ func mergeConfiguredValues(values []string, configured []string) []string {
 
 func mergeConfiguredOptions(opts *Options) {
 	opts.Labels = mergeConfiguredValues(opts.Labels, opts.ConfiguredLabels)
-	opts.Reviewers = mergeConfiguredValues(opts.Reviewers, opts.ConfiguredReviewers)
+	// Note: Reviewers are merged conditionally by effectiveReviewers
+	// based on draft status and ReviewersAddWhen setting.
 	opts.Assignees = mergeConfiguredValues(opts.Assignees, opts.ConfiguredAssignees)
 }
 
+// effectiveReviewers returns the reviewers to add to a change request.
+// Flag-specified reviewers are always included.
+// Configured reviewers are included based on the ReviewersAddWhen setting
+// and the draft status of the change request.
+func effectiveReviewers(opts *Options, isDraft bool) []string {
+	// If addWhen is "ready" and the CR is a draft,
+	// skip configured reviewers.
+	if opts.ReviewersAddWhen == ReviewersAddWhenReady && isDraft {
+		return opts.Reviewers
+	}
+	return mergeConfiguredValues(opts.Reviewers, opts.ConfiguredReviewers)
+}
+
 // NavCommentSync specifies the scope of navigation comment updates.
 type NavCommentSync int
 
@@ -271,6 +286,50 @@ func (d *NavCommentDownstack) UnmarshalText(bs []byte) error {
 	return nil
 }
 
+// ReviewersAddWhen specifies when configured reviewers
+// should be added to change requests.
+type ReviewersAddWhen int
+
+const (
+	// ReviewersAddWhenAlways adds configured reviewers
+	// to all change requests regardless of draft status.
+	//
+	// This is the default.
+	ReviewersAddWhenAlways ReviewersAddWhen = iota
+
+	// ReviewersAddWhenReady adds configured reviewers
+	// only when the change request is not a draft.
+	ReviewersAddWhenReady
+)
+
+var _ encoding.TextUnmarshaler = (*ReviewersAddWhen)(nil)
+
+// String returns the string representation of the ReviewersAddWhen.
+func (r ReviewersAddWhen) String() string {
+	switch r {
+	case ReviewersAddWhenAlways:
+		return "always"
+	case ReviewersAddWhenReady:
+		return "ready"
+	default:
+		return "unknown"
+	}
+}
+
+// UnmarshalText decodes ReviewersAddWhen from text.
+// It supports "always" and "ready" values.
+func (r *ReviewersAddWhen) UnmarshalText(bs []byte) error {
+	switch string(bs) {
+	case "always":
+		*r = ReviewersAddWhenAlways
+	case "ready":
+		*r = ReviewersAddWhenReady
+	default:
+		return fmt.Errorf("invalid value %q: expected always or ready", bs)
+	}
+	return nil
+}
+
 // BatchOptions defines options
 // that are only available to batch submit operations.
 type BatchOptions struct {
@@ -824,6 +883,15 @@ func (h *Handler) submitBranch(
 			updates = append(updates, "set draft to "+strconv.FormatBool(*opts.Draft))
 		}
 
+		// Determine the effective draft status for reviewer handling.
+		// If user is changing draft status, use the new value;
+		// otherwise, use the current draft status.
+		effectiveDraft := pull.Draft
+		if opts.Draft != nil {
+			effectiveDraft = *opts.Draft
+		}
+		reviewers := effectiveReviewers(opts.Options, effectiveDraft)
+
 		// TODO:
 		// We _probably_ don't need to check for existing
 		// reviewers, assignees, etc. because the API contract
@@ -866,13 +934,13 @@ func (h *Handler) submitBranch(
 		}
 
 		// Check for reviewers that would be added.
-		if len(opts.Reviewers) > 0 {
+		if len(reviewers) > 0 {
 			existingReviewerSet := make(map[string]struct{}, len(pull.Reviewers))
 			for _, reviewer := range pull.Reviewers {
 				existingReviewerSet[reviewer] = struct{}{}
 			}
 			var reviewersToAdd []string
-			for _, reviewer := range opts.Reviewers {
+			for _, reviewer := range reviewers {
 				if _, exists := existingReviewerSet[reviewer]; !exists {
 					reviewersToAdd = append(reviewersToAdd, reviewer)
 				}
@@ -921,11 +989,11 @@ func (h *Handler) submitBranch(
 		}
 
 		if len(updates) > 0 {
-			opts := forge.EditChangeOptions{
+			editOpts := forge.EditChangeOptions{
 				Base:         upstreamBase,
 				Draft:        opts.Draft,
 				AddLabels:    opts.Labels,
-				AddReviewers: opts.Reviewers,
+				AddReviewers: reviewers,
 				AddAssignees: opts.Assignees,
 			}
 
@@ -935,7 +1003,7 @@ func (h *Handler) submitBranch(
 				return status, fmt.Errorf("edit CR %v: %w", pull.ID, err)
 			}
 
-			if err := remoteRepo.EditChange(ctx, pull.ID, opts); err != nil {
+			if err := remoteRepo.EditChange(ctx, pull.ID, editOpts); err != nil {
 				return status, fmt.Errorf("edit CR %v: %w", pull.ID, err)
 			}
 		}
@@ -1129,7 +1197,7 @@ func (h *Handler) prepareBranch(
 		store:          h.Store,
 		log:            h.Log,
 		labels:         opts.Labels,
-		reviewers:      opts.Reviewers,
+		reviewers:      effectiveReviewers(opts.Options, draft),
 		assignees:      opts.Assignees,
 	}, nil
 }

internal/handler/submit/handler_test.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"go.abhg.dev/gs/internal/forge"
 	"go.abhg.dev/gs/internal/silog/silogtest"
 	gomock "go.uber.org/mock/gomock"
@@ -54,3 +55,141 @@ func TestBranchSubmit_listChangeTemplates(t *testing.T) {
 		assert.Empty(t, got)
 	})
 }
+
+func TestReviewersAddWhen_UnmarshalText(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    ReviewersAddWhen
+		wantErr string
+	}{
+		{
+			name:  "Always",
+			input: "always",
+			want:  ReviewersAddWhenAlways,
+		},
+		{
+			name:  "Ready",
+			input: "ready",
+			want:  ReviewersAddWhenReady,
+		},
+		{
+			name:    "Invalid",
+			input:   "never",
+			wantErr: `invalid value "never": expected always or ready`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var got ReviewersAddWhen
+			err := got.UnmarshalText([]byte(tt.input))
+
+			if tt.wantErr != "" {
+				require.EqualError(t, err, tt.wantErr)
+				return
+			}
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestReviewersAddWhen_String(t *testing.T) {
+	tests := []struct {
+		name  string
+		value ReviewersAddWhen
+		want  string
+	}{
+		{name: "Always", value: ReviewersAddWhenAlways, want: "always"},
+		{name: "Ready", value: ReviewersAddWhenReady, want: "ready"},
+		{name: "Unknown", value: ReviewersAddWhen(99), want: "unknown"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, tt.value.String())
+		})
+	}
+}
+
+func TestEffectiveReviewers(t *testing.T) {
+	tests := []struct {
+		name                string
+		addWhen             ReviewersAddWhen
+		isDraft             bool
+		flagReviewers       []string
+		configuredReviewers []string
+		want                []string
+	}{
+		{
+			name:                "AlwaysDraft",
+			addWhen:             ReviewersAddWhenAlways,
+			isDraft:             true,
+			flagReviewers:       []string{"alice"},
+			configuredReviewers: []string{"bob"},
+			want:                []string{"alice", "bob"},
+		},
+		{
+			name:                "AlwaysReady",
+			addWhen:             ReviewersAddWhenAlways,
+			isDraft:             false,
+			flagReviewers:       []string{"alice"},
+			configuredReviewers: []string{"bob"},
+			want:                []string{"alice", "bob"},
+		},
+		{
+			name:                "ReadyDraft",
+			addWhen:             ReviewersAddWhenReady,
+			isDraft:             true,
+			flagReviewers:       []string{"alice"},
+			configuredReviewers: []string{"bob"},
+			want:                []string{"alice"},
+		},
+		{
+			name:                "ReadyNotDraft",
+			addWhen:             ReviewersAddWhenReady,
+			isDraft:             false,
+			flagReviewers:       []string{"alice"},
+			configuredReviewers: []string{"bob"},
+			want:                []string{"alice", "bob"},
+		},
+		{
+			name:                "ReadyDraftNoFlags",
+			addWhen:             ReviewersAddWhenReady,
+			isDraft:             true,
+			flagReviewers:       nil,
+			configuredReviewers: []string{"bob"},
+			want:                nil,
+		},
+		{
+			name:                "Deduplication",
+			addWhen:             ReviewersAddWhenAlways,
+			isDraft:             false,
+			flagReviewers:       []string{"alice", "bob"},
+			configuredReviewers: []string{"bob", "charlie"},
+			want:                []string{"alice", "bob", "charlie"},
+		},
+		{
+			name:                "EmptyBoth",
+			addWhen:             ReviewersAddWhenAlways,
+			isDraft:             false,
+			flagReviewers:       nil,
+			configuredReviewers: nil,
+			want:                nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			opts := &Options{
+				Reviewers:           tt.flagReviewers,
+				ConfiguredReviewers: tt.configuredReviewers,
+				ReviewersAddWhen:    tt.addWhen,
+			}
+			got := effectiveReviewers(opts, tt.isDraft)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}