chore: more type docs, fix typo

Signed-off-by: Michael Crenshaw <[email protected]>

api/v1alpha1/commitstatus_types.go

@@ -47,16 +47,18 @@ type CommitStatusSpec struct {
 	// (Gitlab: pending, running, success, failed, canceled)
 	// (Bitbucket: INPROGRESS, STOPPED, SUCCESSFUL, FAILED)
 
+	// Url is a URL that the user can follow to see more details about the status
 	Url string `json:"url"`
 }
 
 // CommitStatusStatus defines the observed state of CommitStatus
 type CommitStatusStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
-	ObservedGeneration int64  `json:"observedGeneration"`
-	Id                 string `json:"id"`
-	Sha                string `json:"sha"`
+	ObservedGeneration int64 `json:"observedGeneration"`
+	// Id is the unique identifier of the commit status, set by the SCM
+	Id  string `json:"id"`
+	Sha string `json:"sha"`
 	// +kubebuilder:default:=pending
 	// +kubebuilder:validation:Enum:=pending;success;failure
 	Phase CommitStatusPhase `json:"phase"`

api/v1alpha1/promotionstrategy_types.go

@@ -31,31 +31,58 @@ type PromotionStrategySpec struct {
 	// +kubebuilder:validation:Required
 	RepositoryReference NamespacedObjectReference `json:"gitRepositoryRef"`
 
+	// DryBranch is the branch that contains the intended system state.
 	// +kubebuilder:validation:Required
-	DryBanch string `json:"dryBranch"`
+	DryBranch string `json:"dryBranch"`
 
+	// ActiveCommitStatuses are commit statuses describing an actively running dry commit. If an active commit status
+	// is failing for an environment, subsequent environments will not deploy the failing commit.
+	//
+	// The commit statuses specified in this field apply to all environments in the promotion sequence. You can also
+	// specify commit statuses for individual environments in the `environments` field.
 	// +kubebuilder:validation:Optional
 	ActiveCommitStatuses []CommitStatusSelector `json:"activeCommitStatuses"`
 
+	// ProposedCommitStatuses are commit statuses describing a proposed dry commit, i.e. one that is not yet running
+	// in a live environment. If a proposed commit status is failing for a given environment, the dry commit will not
+	// be promoted to that environment.
+	//
+	// The commit statuses specified in this field apply to all environments in the promotion sequence. You can also
+	// specify commit statuses for individual environments in the `environments` field.
 	// +kubebuilder:validation:Optional
 	ProposedCommitStatuses []CommitStatusSelector `json:"proposedCommitStatuses"`
 
+	// Environments is the sequence of environments that a dry commit will be promoted through.
 	// +kubebuilder:validation:MinItems:=1
 	Environments []Environment `json:"environments"`
 }
 
 type Environment struct {
 	// +kubebuilder:validation:Required
 	Branch string `json:"branch"`
+	// AutoMerge determines whether the dry commit should be automatically merged into the next branch in the sequence.
+	// If false, the dry commit will be proposed but not merged.
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:default:=true
 	AutoMerge *bool `json:"autoMerge,omitempty"`
+	// ActiveCommitStatuses are commit statuses describing an actively running dry commit. If an active commit status
+	// is failing for an environment, subsequent environments will not deploy the failing commit.
+	//
+	// The commit statuses specified in this field apply to this environment only. You can also specify commit statuses
+	// for all environments in the `spec.activeCommitStatuses` field.
 	// +kubebuilder:validation:Optional
 	ActiveCommitStatuses []CommitStatusSelector `json:"activeCommitStatuses"`
+	// ProposedCommitStatuses are commit statuses describing a proposed dry commit, i.e. one that is not yet running
+	// in a live environment. If a proposed commit status is failing for a given environment, the dry commit will not
+	// be promoted to that environment.
+	//
+	// The commit statuses specified in this field apply to this environment only. You can also specify commit statuses
+	// for all environments in the `spec.proposedCommitStatuses` field.
 	// +kubebuilder:validation:Optional
 	ProposedCommitStatuses []CommitStatusSelector `json:"proposedCommitStatuses"`
 }
 
+// GetAutoMerge returns the value of the AutoMerge field, defaulting to true if the field is nil.
 func (e *Environment) GetAutoMerge() bool {
 	if e.AutoMerge == nil {
 		return true

config/crd/bases/promoter.argoproj.io_commitstatuses.yaml

@@ -69,6 +69,8 @@ spec:
               sha:
                 type: string
               url:
+                description: Url is a URL that the user can follow to see more details
+                  about the status
                 type: string
             required:
             - description
@@ -82,6 +84,8 @@ spec:
             description: CommitStatusStatus defines the observed state of CommitStatus
             properties:
               id:
+                description: Id is the unique identifier of the commit status, set
+                  by the SCM
                 type: string
               observedGeneration:
                 description: |-

config/crd/bases/promoter.argoproj.io_promotionstrategies.yaml

@@ -47,6 +47,12 @@ spec:
             description: PromotionStrategySpec defines the desired state of PromotionStrategy
             properties:
               activeCommitStatuses:
+                description: |-
+                  ActiveCommitStatuses are commit statuses describing an actively running dry commit. If an active commit status
+                  is failing for an environment, subsequent environments will not deploy the failing commit.
+
+                  The commit statuses specified in this field apply to all environments in the promotion sequence. You can also
+                  specify commit statuses for individual environments in the `environments` field.
                 items:
                   properties:
                     key:
@@ -57,11 +63,21 @@ spec:
                   type: object
                 type: array
               dryBranch:
+                description: DryBranch is the branch that contains the intended system
+                  state.
                 type: string
               environments:
+                description: Environments is the sequence of environments that a dry
+                  commit will be promoted through.
                 items:
                   properties:
                     activeCommitStatuses:
+                      description: |-
+                        ActiveCommitStatuses are commit statuses describing an actively running dry commit. If an active commit status
+                        is failing for an environment, subsequent environments will not deploy the failing commit.
+
+                        The commit statuses specified in this field apply to this environment only. You can also specify commit statuses
+                        for all environments in the `spec.activeCommitStatuses` field.
                       items:
                         properties:
                           key:
@@ -73,10 +89,20 @@ spec:
                       type: array
                     autoMerge:
                       default: true
+                      description: |-
+                        AutoMerge determines whether the dry commit should be automatically merged into the next branch in the sequence.
+                        If false, the dry commit will be proposed but not merged.
                       type: boolean
                     branch:
                       type: string
                     proposedCommitStatuses:
+                      description: |-
+                        ProposedCommitStatuses are commit statuses describing a proposed dry commit, i.e. one that is not yet running
+                        in a live environment. If a proposed commit status is failing for a given environment, the dry commit will not
+                        be promoted to that environment.
+
+                        The commit statuses specified in this field apply to this environment only. You can also specify commit statuses
+                        for all environments in the `spec.proposedCommitStatuses` field.
                       items:
                         properties:
                           key:
@@ -101,6 +127,13 @@ spec:
                 - name
                 type: object
               proposedCommitStatuses:
+                description: |-
+                  ProposedCommitStatuses are commit statuses describing a proposed dry commit, i.e. one that is not yet running
+                  in a live environment. If a proposed commit status is failing for a given environment, the dry commit will not
+                  be promoted to that environment.
+
+                  The commit statuses specified in this field apply to all environments in the promotion sequence. You can also
+                  specify commit statuses for individual environments in the `environments` field.
                 items:
                   properties:
                     key:

internal/controller/promotionstrategy_controller_test.go

@@ -684,7 +684,7 @@ func promotionStrategyResource(ctx context.Context, name, namespace string) (str
 			Namespace: namespace,
 		},
 		Spec: promoterv1alpha1.PromotionStrategySpec{
-			DryBanch: "main",
+			DryBranch: "main",
 			RepositoryReference: promoterv1alpha1.NamespacedObjectReference{
 				Name:      name,
 				Namespace: namespace,