review remarks 3

api/openapi-spec/v3/apis__batch__v1_openapi.json

@@ -451,7 +451,7 @@
             "type": "string"
           },
           "ready": {
-            "description": "The number of pods which have a Ready condition. The value is zero (or nil) for finished jobs.",
+            "description": "The number of pods which have a Ready condition. The value is zero (or null) for finished jobs.",
             "format": "int32",
             "type": "integer"
           },
@@ -469,7 +469,7 @@
             "type": "integer"
           },
           "terminating": {
-            "description": "The number of pods which are terminating (in phase Pending or Running and have a deletionTimestamp). The value is zero (or nil) for finished jobs.\n\nThis field is beta-level. The job controller populates the field when the feature gate JobPodReplacementPolicy is enabled (enabled by default).",
+            "description": "The number of pods which are terminating (in phase Pending or Running and have a deletionTimestamp). The value is zero (or null) for finished jobs.\n\nThis field is beta-level. The job controller populates the field when the feature gate JobPodReplacementPolicy is enabled (enabled by default).",
             "format": "int32",
             "type": "integer"
           },

pkg/apis/batch/types.go

@@ -475,15 +475,15 @@ type JobStatus struct {
 
 	// The number of pods which are terminating (in phase Pending or Running
 	// and have a deletionTimestamp).
-	// The value is zero (or nil) for finished jobs.
+	// The value is zero (or null) for finished jobs.
 	//
 	// This field is beta-level. The job controller populates the field when
 	// the feature gate JobPodReplacementPolicy is enabled (enabled by default).
 	// +optional
 	Terminating *int32
 
 	// The number of active pods which have a Ready condition.
-	// The value is zero (or nil) for finished jobs.
+	// The value is zero (or null) for finished jobs.
 	// +optional
 	Ready *int32
 

pkg/apis/batch/validation/validation.go

@@ -605,11 +605,16 @@ func ValidateJobStatusUpdate(job, oldJob *batch.Job, opts JobStatusValidationOpt
 		}
 	}
 	if opts.RejectMutatingCompletionTime {
+		// Note that we check the condition only when `job.Status.CompletionTime != nil`, this is because
+		// we don't want to block transitions to completionTime = nil when the job is not finished yet.
+		// Setting completionTime = nil for finished jobs is prevented in RejectCompleteJobWithoutCompletionTime.
 		if job.Status.CompletionTime != nil && oldJob.Status.CompletionTime != nil && !ptr.Equal(job.Status.CompletionTime, oldJob.Status.CompletionTime) {
 			allErrs = append(allErrs, field.Invalid(statusFld.Child("completionTime"), job.Status.CompletionTime, "completionTime cannot be mutated"))
 		}
 	}
 	if opts.RejectStartTimeUpdateForUnsuspendedJob {
+		// Note that we check `oldJob.Status.StartTime != nil` to allow transitioning from
+		// startTime = nil to startTime != nil for unsuspended jobs, which is a desired transition.
 		if oldJob.Status.StartTime != nil && !ptr.Equal(oldJob.Status.StartTime, job.Status.StartTime) && !ptr.Deref(job.Spec.Suspend, false) {
 			allErrs = append(allErrs, field.Required(statusFld.Child("startTime"), "startTime cannot be removed for unsuspended job"))
 		}

staging/src/k8s.io/api/batch/v1/types.go

@@ -490,7 +490,7 @@ type JobStatus struct {
 
 	// The number of pods which are terminating (in phase Pending or Running
 	// and have a deletionTimestamp).
-	// The value is zero (or nil) for finished jobs.
+	// The value is zero (or null) for finished jobs.
 	//
 	// This field is beta-level. The job controller populates the field when
 	// the feature gate JobPodReplacementPolicy is enabled (enabled by default).
@@ -541,7 +541,7 @@ type JobStatus struct {
 	UncountedTerminatedPods *UncountedTerminatedPods `json:"uncountedTerminatedPods,omitempty" protobuf:"bytes,8,opt,name=uncountedTerminatedPods"`
 
 	// The number of pods which have a Ready condition.
-	// The value is zero (or nil) for finished jobs.
+	// The value is zero (or null) for finished jobs.
 	// +optional
 	Ready *int32 `json:"ready,omitempty" protobuf:"varint,9,opt,name=ready"`
 }