feat(pipelines): room for extra sequential intermediary actions in Cd…

…kStage addApplication()

naming changes as per reviewer recommendation

Closes aws#11333

packages/@aws-cdk/pipelines/README.md

@@ -342,12 +342,12 @@ testingStage.addApplication(new MyApplication2(this, 'MyApp2', {
 ```
 
 Even more, adding a manual approval action or reserving space for some extra sequential actions 
-before executing the Change Set is also possible.
+between 'Prepare' and 'Execute' ChangeSet actions is possible.
 
 ```ts
   pipeline.addApplicationStage(new MyApplication(this, 'Production'), {
     manualApprovals: true,
-    roomForIntermediaryActions: 1,
+    extraRunOrderSpace: 1,
   });
 ```
 

packages/@aws-cdk/pipelines/lib/stage.ts

@@ -76,7 +76,7 @@ export class CdkStage extends CoreConstruct {
    */
   public addApplication(appStage: Stage, options: AddStageOptions = {}) {
     const asm = appStage.synth();
-    const roomForIntermediaryActions = options.roomForIntermediaryActions ?? 0;
+    const extraRunOrderSpace = options.extraRunOrderSpace ?? 0;
 
     if (asm.stacks.length === 0) {
       // If we don't check here, a more puzzling "stage contains no actions"
@@ -89,8 +89,8 @@ export class CdkStage extends CoreConstruct {
       stack => stack.dependencies.map(d => d.id));
 
     for (const stacks of sortedTranches) {
-      const runOrder = this.nextSequentialRunOrder(roomForIntermediaryActions + 2); // 2 actions for Prepare/Execute ChangeSet
-      let executeRunOrder = runOrder + roomForIntermediaryActions + 1;
+      const runOrder = this.nextSequentialRunOrder(extraRunOrderSpace + 2); // 2 actions for Prepare/Execute ChangeSet
+      let executeRunOrder = runOrder + extraRunOrderSpace + 1;
 
       // If we need to insert a manual approval action, then what's the executeRunOrder
       // now is where we add a manual approval step, and we allocate 1 more runOrder
@@ -373,14 +373,14 @@ export interface AddStageOptions {
    */
   readonly manualApprovals?: boolean;
   /**
-   * Add room for extra sequetial intermediary actions
+   * Add room for extra actions
    *
-   * This increases the executeRunOrder of the execute change set action with
-   * the value passed.
+   * You can use this to make extra room in the runOrder sequence between the
+   * changeset 'prepare' and 'execute' actions and insert your own actions there.
    *
    * @default 0
    */
-  readonly roomForIntermediaryActions?: number;
+  readonly extraRunOrderSpace?: number;
 }
 
 /**

packages/@aws-cdk/pipelines/test/stack-ordering.test.ts

@@ -78,10 +78,10 @@ test('manual approval is inserted in correct location', () => {
   });
 });
 
-test('room for sequential intermediary actions is reserved', () => {
+test('extra space for sequential intermediary actions is reserved', () => {
   // WHEN
   pipeline.addApplicationStage(new TwoStackApp(app, 'MyApp'), {
-    roomForIntermediaryActions: 1,
+    extraRunOrderSpace: 1,
   });
 
   // THEN