Make release_id required for pipeline promotions

- Change release_id from Optional to Required in schema
- Remove conditional logic in Create function since release_id is always present
- Update documentation to reflect required field
- Update unit test to validate release_id as required field
- Simplify examples and descriptions to focus on specific release promotion
- This provides clearer, more predictable behavior for users

Author: heroku-johnny

docs/resources/pipeline_promotion.md

@@ -11,24 +11,15 @@ description: |-
 Provides a [Heroku Pipeline Promotion](https://devcenter.heroku.com/articles/pipelines)
 resource.
 
-A pipeline promotion allows you to deploy releases from one app to other apps within the same
+A pipeline promotion allows you to deploy a specific release from one app to other apps within the same
 pipeline. This enables infrastructure-as-code workflow for promoting code between pipeline stages
 such as staging to production.
 
-You can promote either the latest release from the source app, or specify a particular release by ID.
-
 ## Example Usage
 
 ```hcl
-# Basic promotion from staging to production (latest release)
+# Basic promotion from staging to production
 resource "heroku_pipeline_promotion" "staging_to_prod" {
-  pipeline      = heroku_pipeline.my_app.id
-  source_app_id = heroku_app.staging.id
-  targets       = [heroku_app.production.id]
-}
-
-# Promotion of a specific release
-resource "heroku_pipeline_promotion" "specific_release" {
   pipeline      = heroku_pipeline.my_app.id
   source_app_id = heroku_app.staging.id
   release_id    = "01234567-89ab-cdef-0123-456789abcdef"
@@ -39,6 +30,7 @@ resource "heroku_pipeline_promotion" "specific_release" {
 resource "heroku_pipeline_promotion" "staging_to_multiple" {
   pipeline      = heroku_pipeline.my_app.id
   source_app_id = heroku_app.staging.id
+  release_id    = "01234567-89ab-cdef-0123-456789abcdef"
   targets       = [
     heroku_app.production.id,
     heroku_app.demo.id
@@ -53,7 +45,7 @@ The following arguments are supported:
 * `pipeline` - (Required) The UUID of the pipeline containing the apps.
 * `source_app_id` - (Required) The UUID of the source app to promote from.
 * `targets` - (Required) Set of UUIDs of target apps to promote to.
-* `release_id` - (Optional) The UUID of a specific release to promote. If not specified, promotes the latest release from the source app.
+* `release_id` - (Required) The UUID of the specific release to promote.
 
 ## Attributes Reference
 
@@ -69,6 +61,6 @@ The following attributes are exported:
 * Pipeline promotions are immutable - they cannot be updated or modified after creation.
 * All apps (source and targets) must be in the same pipeline.
 * All apps must have the same generation (Cedar or Fir). See [`heroku_pipeline`](./pipeline.html) for generation compatibility requirements.
-* The source app must have at least one release to promote.
-* Promotions copy either the latest release (if no `release_id` specified) or the specified release to all target apps.
+* The specified release must exist on the source app.
+* Promotions copy the specified release to all target apps.
 

heroku/resource_heroku_pipeline_promotion.go

@@ -39,10 +39,10 @@ func resourceHerokuPipelinePromotion() *schema.Resource {
 
 			"release_id": {
 				Type:         schema.TypeString,
-				Optional:     true,
+				Required:     true,
 				ForceNew:     true,
 				ValidateFunc: validation.IsUUID,
-				Description:  "Specific release ID to promote (optional, defaults to latest release)",
+				Description:  "Release ID to promote to target apps",
 			},
 
 			"targets": {
@@ -94,14 +94,12 @@ func resourceHerokuPipelinePromotionCreate(d *schema.ResourceData, meta interfac
 		ID *string `json:"id,omitempty" url:"id,omitempty,key"`
 	}{ID: &sourceAppID}
 
-	// Add release_id if specified
-	if releaseID, ok := d.GetOk("release_id"); ok {
-		releaseIDStr := releaseID.(string)
-		opts.Source.Release = &struct {
-			ID *string `json:"id,omitempty" url:"id,omitempty,key"`
-		}{ID: &releaseIDStr}
-		log.Printf("[DEBUG] Promoting specific release: %s", releaseIDStr)
-	}
+	// Set required release_id
+	releaseIDStr := d.Get("release_id").(string)
+	opts.Source.Release = &struct {
+		ID *string `json:"id,omitempty" url:"id,omitempty,key"`
+	}{ID: &releaseIDStr}
+	log.Printf("[DEBUG] Promoting release: %s", releaseIDStr)
 
 	// Convert targets set to slice
 	for _, target := range targets.List() {

heroku/resource_heroku_pipeline_promotion_test.go

@@ -10,7 +10,7 @@ func TestResourceHerokuPipelinePromotion_Schema(t *testing.T) {
 	resource := resourceHerokuPipelinePromotion()
 
 	// Test required fields
-	requiredFields := []string{"pipeline", "source_app_id", "targets"}
+	requiredFields := []string{"pipeline", "source_app_id", "targets", "release_id"}
 	for _, field := range requiredFields {
 		if _, ok := resource.Schema[field]; !ok {
 			t.Errorf("Required field %s not found in schema", field)
@@ -23,20 +23,6 @@ func TestResourceHerokuPipelinePromotion_Schema(t *testing.T) {
 		}
 	}
 
-	// Test optional fields
-	optionalFields := []string{"release_id"}
-	for _, field := range optionalFields {
-		if _, ok := resource.Schema[field]; !ok {
-			t.Errorf("Optional field %s not found in schema", field)
-		}
-		if !resource.Schema[field].Optional {
-			t.Errorf("Field %s should be optional", field)
-		}
-		if !resource.Schema[field].ForceNew {
-			t.Errorf("Field %s should be ForceNew", field)
-		}
-	}
-
 	// Test computed fields
 	computedFields := []string{"status", "created_at", "promoted_release_id"}
 	for _, field := range computedFields {