| name | add-stage-field |
| description | Use when adding a new parameter or field to the Stage struct in stage/stage.go, to ensure all required locations are updated |
Add Stage Field
When adding a new field to the Stage struct, you must update multiple locations. Missing any causes silent bugs (fields not inherited, not merged, missing defaults).
Checklist
Update these locations in order:
-
stage/stage.go — Stage struct: Add the field with a json:"field_name,omitempty" tag. Use pointer types (*bool, *int, *string) for optional fields that participate in inheritance (nil = "not set, inherit from parent").
-
stage/stage_utils.go — MergeWith(): Add merge logic. For pointer fields: if other.Field != nil { s.Field = other.Field }. For slices: s.Field = append(s.Field, other.Field...). For maps: iterate and merge key-by-key (nil value = delete key).
-
stage/stage_utils.go — setDefaults(): Set a default value if the field needs one (e.g., false for bool flags, 0 for counts). Only needed for fields that must have a non-nil value before execution.
-
stage/stage_utils.go — propagateStates(): Propagate to child stages if the field should be inherited. Pattern: if nextStage.Field == nil { nextStage.Field = s.Field }. Skip this if the field is stage-local only.
-
stage/stage.go — newStreamInstance(): Copy the field if it's relevant to stream (concurrent) execution. Most execution-related fields should be copied here.
-
Wiki: Parameters: Document the new parameter with its JSON key, type, default, and description.
-
Wiki: Configuring PBench - Inherited Parameters: Add to the inherited list if propagated in step 4.
Verification
After implementation, grep to confirm the field name appears in all required locations:
grep -n 'FieldName' stage/stage.go stage/stage_utils.go
Ensure the count matches expectations (struct definition + MergeWith + setDefaults if needed + propagateStates if inherited + newStreamInstance if stream-relevant).
