From dd813d815831156d85acbaa12be01789663b8b62 Mon Sep 17 00:00:00 2001
From: Adam Ruka <adamruka@amazon.com>
Date: Tue, 14 Aug 2018 10:41:56 -0700
Subject: [PATCH] refactor(aws-codepipeline): Pass the Pipeline to Stage
 through props instead of parent.

BREAKING CHANGE: this commit changes the way we pass a Pipeline to a newly created Stage.
Instead of passing it as a parent, in the first argument of the constructor,
we now pass it through a separate props object, in the pipeline property.
This is in order to make Stage more consistent with other Constructs,
and with the changes made to the Actions API in #459.
---
 packages/@aws-cdk/aws-codebuild/README.md     |  8 +++--
 packages/@aws-cdk/aws-codecommit/README.md    |  6 ++--
 packages/@aws-cdk/aws-codepipeline/README.md  | 12 +++----
 .../@aws-cdk/aws-codepipeline/lib/pipeline.ts | 25 ++++++-------
 .../@aws-cdk/aws-codepipeline/lib/stage.ts    | 35 ++++++++++++-------
 .../test/integ.cfn-template-from-repo.lit.ts  |  4 +--
 .../test/integ.lambda-pipeline.ts             |  4 +--
 .../test/integ.pipeline-cfn.ts                |  4 +--
 .../test/integ.pipeline-code-commit-build.ts  |  4 +--
 .../test/integ.pipeline-code-commit.ts        |  4 +--
 .../test/integ.pipeline-events.ts             |  4 +--
 .../aws-codepipeline/test/test.action.ts      |  4 +--
 .../test.cloudformation-pipeline-actions.ts   | 10 +++---
 .../test/test.general-validation.ts           |  6 ++--
 .../aws-codepipeline/test/test.pipeline.ts    | 16 ++++-----
 packages/@aws-cdk/aws-lambda/README.md        |  4 ++-
 packages/@aws-cdk/aws-s3/README.md            |  4 ++-
 17 files changed, 88 insertions(+), 66 deletions(-)

diff --git a/packages/@aws-cdk/aws-codebuild/README.md b/packages/@aws-cdk/aws-codebuild/README.md
index 7e96f68ca03ec..4408964272142 100644
--- a/packages/@aws-cdk/aws-codebuild/README.md
+++ b/packages/@aws-cdk/aws-codebuild/README.md
@@ -50,14 +50,18 @@ const project = new codebuild.PipelineProject(this, 'MyProject');
 
 const pipeline = new codepipeline.Pipeline(this, 'MyPipeline');
 
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
+const sourceStage = new codepipeline.Stage(this, 'Source', {
+    pipeline,
+});
 const sourceAction = new codecommit.PipelineSource(this, 'CodeCommit', {
     stage: sourceStage,
     artifactName: 'SourceOutput',
     repository,
 });
 
-const buildStage = new codepipeline.Stage(pipeline, 'Build');
+const buildStage = new codepipeline.Stage(this, 'Build', {
+    pipeline,
+});
 new codebuild.PipelineBuildAction(this, 'CodeBuild', {
     stage: buildStage,
     inputArtifact: sourceAction.artifact,
diff --git a/packages/@aws-cdk/aws-codecommit/README.md b/packages/@aws-cdk/aws-codecommit/README.md
index d268be37f5b9b..13f58fe15e663 100644
--- a/packages/@aws-cdk/aws-codecommit/README.md
+++ b/packages/@aws-cdk/aws-codecommit/README.md
@@ -38,10 +38,12 @@ const repository = new codecommit.Repository( // ...
 const pipeline = new codepipeline.Pipeline(this, 'MyPipeline', {
     pipelineName: 'MyPipeline',
 });
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
+const sourceStage = new codepipeline.Stage(this, 'Source', {
+    pipeline,
+}));
 const sourceAction = new codecommit.PipelineSource(this, 'CodeCommit', {
     stage: sourceStage,
-    artifactName: 'SourceOutput', //name can be arbitrary
+    artifactName: 'SourceOutput', // name can be arbitrary
     repository,
 });
 // use sourceAction.artifact as the inputArtifact to later Actions...
diff --git a/packages/@aws-cdk/aws-codepipeline/README.md b/packages/@aws-cdk/aws-codepipeline/README.md
index e37b61d115e03..9cbb2d48b3dad 100644
--- a/packages/@aws-cdk/aws-codepipeline/README.md
+++ b/packages/@aws-cdk/aws-codepipeline/README.md
@@ -1,6 +1,6 @@
 ## AWS CodePipeline construct library
 
-Construct an empty pipeline:
+Construct an empty Pipeline:
 
 ```ts
 const pipeline = new Pipeline(this, 'MyFirstPipeline', {
@@ -8,15 +8,15 @@ const pipeline = new Pipeline(this, 'MyFirstPipeline', {
 });
 ```
 
-All of the components of a pipeline are modeled as constructs.
-
-Append a stage to the pipeline:
+Append a Stage to the Pipeline:
 
 ```ts
-const sourceStage = new Stage(pipeline, 'Source');
+const sourceStage = new Stage(this, 'Source', {
+    pipeline,
+});
 ```
 
-Add an action to a stage:
+Add an Action to a Stage:
 
 ```ts
 new codecommit.PipelineSource(this, 'Source', {
diff --git a/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts b/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts
index 29a96cf5c0b7c..925b5db68ce10 100644
--- a/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts
+++ b/packages/@aws-cdk/aws-codepipeline/lib/pipeline.ts
@@ -211,21 +211,22 @@ export class Pipeline extends cdk.Construct implements events.IEventRuleTarget {
     }
 
     /**
-     * If a stage is added as a child, add it to the list of stages.
-     * TODO: This is a hack that should be removed once the CDK has an
-     *       onChildAdded type hook.
-     * @override
+     * Adds a Stage to this Pipeline.
+     * This is an internal operation -
+     * a Stage is added to a Pipeline when it's constructed
+     * (the Pipeline is passed through the {@link StageProps#pipeline} property),
+     * so there is never a need to call this method explicitly.
+     *
+     * @param stage the newly created Stage to add to this Pipeline
      */
-    protected addChild(child: cdk.Construct, name: string) {
-        super.addChild(child, name);
-        if (child instanceof Stage) {
-            this.appendStage(child);
+    public _addStage(stage: Stage): void {
+        // _addStage should be idempotent, in case a customer ever calls it directly
+        if (this.stages.includes(stage)) {
+            return;
         }
-    }
 
-    private appendStage(stage: Stage) {
-        if (this.stages.find(x => x.id === stage.id)) {
-            throw new Error(`A stage with name '${stage.id}' already exists`);
+        if (this.stages.find(x => x.name === stage.name)) {
+            throw new Error(`A stage with name '${stage.name}' already exists`);
         }
 
         this.stages.push(stage);
diff --git a/packages/@aws-cdk/aws-codepipeline/lib/stage.ts b/packages/@aws-cdk/aws-codepipeline/lib/stage.ts
index 8da2ac5d871dd..b2094f0ff3127 100644
--- a/packages/@aws-cdk/aws-codepipeline/lib/stage.ts
+++ b/packages/@aws-cdk/aws-codepipeline/lib/stage.ts
@@ -6,16 +6,29 @@ import { cloudformation } from './codepipeline.generated';
 import { Pipeline } from './pipeline';
 
 /**
- * A stage in a pipeline. Stages are added to a pipeline by constructing a Stage with
- * the pipeline as the first argument to the constructor.
+ * The construction properties for {@link Stage}.
+ */
+export interface StageProps {
+    /**
+     * The Pipeline to add the newly created Stage to.
+     */
+    pipeline: Pipeline;
+}
+
+/**
+ * A Stage in a Pipeline.
+ * Stages are added to a Pipeline by constructing a new Stage,
+ * and passing the Pipeline it belongs to through the {@link StageProps#pipeline} attribute.
  *
  * @example
- * // add a stage to a pipeline
- * new Stage(pipeline, 'MyStage');
+ *   // add a Stage to a Pipeline
+ *   new Stage(this, 'MyStage', {
+ *       pipeline: myPipeline,
+ *   });
  */
 export class Stage extends cdk.Construct implements actions.IStage {
     /**
-     * The Pipeline this stage is a member of
+     * The Pipeline this Stage is a part of.
      */
     public readonly pipeline: Pipeline;
     public readonly name: string;
@@ -23,17 +36,15 @@ export class Stage extends cdk.Construct implements actions.IStage {
     private readonly _actions = new Array<actions.Action>();
 
     /**
-     * Append a new stage to the pipeline
-     *
-     * Only a Pipeline can be passed in as a parent because stages should
-     * always be attached to a pipeline. It's illogical to construct a Stage
-     * with any other parent.
+     * Create a new Stage.
      */
-    constructor(parent: Pipeline, name: string) {
+    constructor(parent: cdk.Construct, name: string, props: StageProps) {
         super(parent, name);
         this.name = name;
-        this.pipeline = parent;
+        this.pipeline = props.pipeline;
         actions.validateName('Stage', name);
+
+        this.pipeline._addStage(this);
     }
 
     /**
diff --git a/packages/@aws-cdk/aws-codepipeline/test/integ.cfn-template-from-repo.lit.ts b/packages/@aws-cdk/aws-codepipeline/test/integ.cfn-template-from-repo.lit.ts
index d6587bf2e50a3..c9587e759eb97 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/integ.cfn-template-from-repo.lit.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/integ.cfn-template-from-repo.lit.ts
@@ -13,7 +13,7 @@ const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
 const repo = new codecommit.Repository(stack, 'TemplateRepo', {
     repositoryName: 'template-repo'
 });
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
+const sourceStage = new codepipeline.Stage(pipeline, 'Source', { pipeline });
 const source = new codecommit.PipelineSource(stack, 'Source', {
     stage: sourceStage,
     repository: repo,
@@ -21,7 +21,7 @@ const source = new codecommit.PipelineSource(stack, 'Source', {
 });
 
 // Deployment stage: create and deploy changeset with manual approval
-const prodStage = new codepipeline.Stage(pipeline, 'Deploy');
+const prodStage = new codepipeline.Stage(pipeline, 'Deploy', { pipeline });
 const stackName = 'OurStack';
 const changeSetName = 'StagedChangeSet';
 
diff --git a/packages/@aws-cdk/aws-codepipeline/test/integ.lambda-pipeline.ts b/packages/@aws-cdk/aws-codepipeline/test/integ.lambda-pipeline.ts
index c526fde753311..b67d284a95c81 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/integ.lambda-pipeline.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/integ.lambda-pipeline.ts
@@ -9,7 +9,7 @@ const stack = new cdk.Stack(app, 'aws-cdk-codepipeline-lambda');
 
 const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
 
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
+const sourceStage = new codepipeline.Stage(pipeline, 'Source', { pipeline });
 const bucket = new s3.Bucket(stack, 'PipelineBucket', {
     versioned: true,
 });
@@ -29,7 +29,7 @@ const lambdaFun = new lambda.Function(stack, 'LambdaFun', {
     handler: 'index.handler',
     runtime: lambda.Runtime.NodeJS610,
 });
-const lambdaStage = new codepipeline.Stage(pipeline, 'Lambda');
+const lambdaStage = new codepipeline.Stage(pipeline, 'Lambda', { pipeline });
 new lambda.PipelineInvokeAction(stack, 'Lambda', {
     stage: lambdaStage,
     lambda: lambdaFun,
diff --git a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-cfn.ts b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-cfn.ts
index 68d7061d4fa80..96e8a438ff2d0 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-cfn.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-cfn.ts
@@ -12,7 +12,7 @@ const stack = new cdk.Stack(app, 'aws-cdk-codepipeline-cloudformation');
 
 const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
 
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
+const sourceStage = new codepipeline.Stage(pipeline, 'Source', { pipeline });
 const bucket = new s3.Bucket(stack, 'PipelineBucket', {
     versioned: true,
 });
@@ -23,7 +23,7 @@ const source = new s3.PipelineSource(stack, 'Source', {
     bucketKey: 'key',
 });
 
-const cfnStage = new codepipeline.Stage(pipeline, 'CFN');
+const cfnStage = new codepipeline.Stage(stack, 'CFN', { pipeline });
 
 const changeSetName = "ChangeSetIntegTest";
 const stackName = "IntegTest-TestActionStack";
diff --git a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit-build.ts b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit-build.ts
index a1d7a202d6cbc..a006fbe2f55e5 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit-build.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit-build.ts
@@ -13,7 +13,7 @@ const repository = new codecommit.Repository(stack, 'MyRepo', {
 
 const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
 
-const sourceStage = new codepipeline.Stage(pipeline, 'source');
+const sourceStage = new codepipeline.Stage(pipeline, 'source', { pipeline });
 const source = new codecommit.PipelineSource(stack, 'source', {
     stage: sourceStage,
     artifactName: 'SourceArtifact',
@@ -24,7 +24,7 @@ const project = new codebuild.Project(stack, 'MyBuildProject', {
     source: new codebuild.CodePipelineSource(),
 });
 
-const buildStage = new codepipeline.Stage(pipeline, 'build');
+const buildStage = new codepipeline.Stage(pipeline, 'build', { pipeline });
 new codebuild.PipelineBuildAction(buildStage, 'build', {
     stage: buildStage,
     inputArtifact: source.artifact,
diff --git a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit.ts b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit.ts
index 967e2acfaad2d..43fabb7e9914f 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-code-commit.ts
@@ -10,14 +10,14 @@ const repo = new codecommit.Repository(stack, 'MyRepo', { repositoryName: 'my-re
 
 const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
 
-const sourceStage = new codepipeline.Stage(pipeline, 'source');
+const sourceStage = new codepipeline.Stage(pipeline, 'source', { pipeline });
 new codecommit.PipelineSource(stack, 'source', {
     stage: sourceStage,
     artifactName: 'SourceArtifact',
     repository: repo,
 });
 
-const buildStage = new codepipeline.Stage(pipeline, 'build');
+const buildStage = new codepipeline.Stage(stack, 'build', { pipeline });
 new codepipeline.ManualApprovalAction(stack, 'manual', {
     stage: buildStage,
 });
diff --git a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-events.ts b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-events.ts
index 281517ff303f5..e19276f6fcfd1 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-events.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/integ.pipeline-events.ts
@@ -11,8 +11,8 @@ const app = new cdk.App(process.argv);
 const stack = new cdk.Stack(app, 'aws-cdk-pipeline-event-target');
 
 const pipeline = new codepipeline.Pipeline(stack, 'MyPipeline');
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
-const buildStage = new codepipeline.Stage(pipeline, 'Build');
+const sourceStage = new codepipeline.Stage(stack, 'Source', { pipeline });
+const buildStage = new codepipeline.Stage(stack, 'Build', { pipeline });
 
 const repository = new codecommit.Repository(stack, 'CodeCommitRepo', {
     repositoryName: 'foo'
diff --git a/packages/@aws-cdk/aws-codepipeline/test/test.action.ts b/packages/@aws-cdk/aws-codepipeline/test/test.action.ts
index e1943e9973ec8..0881439e6b3e1 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/test.action.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/test.action.ts
@@ -64,7 +64,7 @@ export = {
     'standard action with artifacts'(test: Test) {
         const stack = new cdk.Stack();
         const pipeline = new codepipeline.Pipeline(stack, 'pipeline');
-        const stage = new codepipeline.Stage(pipeline, 'stage');
+        const stage = new codepipeline.Stage(stack, 'stage', { pipeline });
         const action = new TestAction(stack, 'TestAction', {
             stage,
             artifactBounds: actions.defaultBounds(),
@@ -95,7 +95,7 @@ export = {
 function boundsValidationResult(numberOfArtifacts: number, min: number, max: number): string[] {
     const stack = new cdk.Stack();
     const pipeline = new codepipeline.Pipeline(stack, 'pipeline');
-    const stage = new codepipeline.Stage(pipeline, 'stage');
+    const stage = new codepipeline.Stage(stack, 'stage', { pipeline });
     const action = new TestAction(stack, 'TestAction', {
         stage,
         artifactBounds: actions.defaultBounds(),
diff --git a/packages/@aws-cdk/aws-codepipeline/test/test.cloudformation-pipeline-actions.ts b/packages/@aws-cdk/aws-codepipeline/test/test.cloudformation-pipeline-actions.ts
index 4a28eff000bc0..614c4d91dc1ae 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/test.cloudformation-pipeline-actions.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/test.cloudformation-pipeline-actions.ts
@@ -24,7 +24,7 @@ export = {
     /** Source! */
     const repo = new Repository(stack, 'MyVeryImportantRepo', { repositoryName: 'my-very-important-repo' });
 
-    const sourceStage = new Stage(pipeline, 'source');
+    const sourceStage = new Stage(pipeline, 'source', { pipeline });
 
     const source = new PipelineSource(stack, 'source', {
       stage: sourceStage,
@@ -34,7 +34,7 @@ export = {
 
     /** Build! */
 
-    const buildStage = new Stage(pipeline, 'build');
+    const buildStage = new Stage(pipeline, 'build', { pipeline });
     const buildArtifacts = new CodePipelineBuildArtifacts();
     const project = new Project(stack, 'MyBuildProject', {
       source: new CodePipelineSource(),
@@ -53,7 +53,7 @@ export = {
     // To execute a change set - yes, you probably do need *:* 🤷‍♀️
     changeSetExecRole.addToPolicy(new PolicyStatement().addAllResources().addAction("*"));
 
-    const prodStage = new Stage(pipeline, 'prod');
+    const prodStage = new Stage(stack, 'prod', { pipeline });
     const stackName = 'BrelandsStack';
     const changeSetName = 'MyMagicalChangeSet';
 
@@ -366,8 +366,8 @@ class TestFixture extends cdk.Stack {
     super();
 
     this.pipeline = new Pipeline(this, 'Pipeline');
-    this.sourceStage = new Stage(this.pipeline, 'Source');
-    this.deployStage = new Stage(this.pipeline, 'Deploy');
+    this.sourceStage = new Stage(this.pipeline, 'Source', { pipeline: this.pipeline });
+    this.deployStage = new Stage(this.pipeline, 'Deploy', { pipeline: this.pipeline });
     this.repo = new Repository(this, 'MyVeryImportantRepo', { repositoryName: 'my-very-important-repo' });
     this.source = new PipelineSource(this, 'Source', {
       stage: this.sourceStage,
diff --git a/packages/@aws-cdk/aws-codepipeline/test/test.general-validation.ts b/packages/@aws-cdk/aws-codepipeline/test/test.general-validation.ts
index bd924908ff957..226007a243e0d 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/test.general-validation.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/test.general-validation.ts
@@ -56,8 +56,8 @@ export = {
         'should fail if Pipeline has a Source Action in a non-first Stage'(test: Test) {
             const stack = new cdk.Stack();
             const pipeline = new Pipeline(stack, 'Pipeline');
-            const firstStage = new Stage(pipeline, 'FirstStage');
-            const secondStage = new Stage(pipeline, 'SecondStage');
+            const firstStage = new Stage(stack, 'FirstStage', { pipeline });
+            const secondStage = new Stage(stack, 'SecondStage', { pipeline });
 
             const bucket = new s3.Bucket(stack, 'PipelineBucket');
             new s3.PipelineSource(stack, 'FirstAction', {
@@ -83,5 +83,5 @@ export = {
 function stageForTesting(): Stage {
     const stack = new cdk.Stack();
     const pipeline = new Pipeline(stack, 'pipeline');
-    return new Stage(pipeline, 'stage');
+    return new Stage(stack, 'stage', { pipeline });
 }
diff --git a/packages/@aws-cdk/aws-codepipeline/test/test.pipeline.ts b/packages/@aws-cdk/aws-codepipeline/test/test.pipeline.ts
index fb75b1e045595..5bcff6d224cb2 100644
--- a/packages/@aws-cdk/aws-codepipeline/test/test.pipeline.ts
+++ b/packages/@aws-cdk/aws-codepipeline/test/test.pipeline.ts
@@ -19,14 +19,14 @@ export = {
         });
 
         const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
-        const sourceStage = new codepipeline.Stage(pipeline, 'source');
+        const sourceStage = new codepipeline.Stage(pipeline, 'source', { pipeline });
         const source = new codecommit.PipelineSource(stack, 'source', {
             stage: sourceStage,
             artifactName: 'SourceArtifact',
             repository,
         });
 
-        const buildStage = new codepipeline.Stage(pipeline, 'build');
+        const buildStage = new codepipeline.Stage(pipeline, 'build', { pipeline });
         const project = new codebuild.Project(stack, 'MyBuildProject', {
            source: new codebuild.CodePipelineSource()
         });
@@ -48,7 +48,7 @@ export = {
 
         const p = new codepipeline.Pipeline(stack, 'P');
 
-        const s1 = new codepipeline.Stage(p, 'Source');
+        const s1 = new codepipeline.Stage(stack, 'Source', { pipeline: p });
         new codepipeline.GitHubSource(stack, 'GH', {
             stage: s1,
             artifactName: 'A',
@@ -58,7 +58,7 @@ export = {
             repo: 'bar'
         });
 
-        const s2 = new codepipeline.Stage(p, 'Two');
+        const s2 = new codepipeline.Stage(stack, 'Two', { pipeline: p });
         new codepipeline.ManualApprovalAction(stack, 'Boo', { stage: s2 });
 
         expect(stack).to(haveResource('AWS::CodePipeline::Pipeline', {
@@ -136,7 +136,7 @@ export = {
 
         const pipeline = new codepipeline.Pipeline(stack, 'PL');
 
-        const stage1 = new codepipeline.Stage(pipeline, 'S1');
+        const stage1 = new codepipeline.Stage(stack, 'S1', { pipeline });
         new s3.PipelineSource(stack, 'A1', {
           stage: stage1,
           artifactName: 'Artifact',
@@ -144,7 +144,7 @@ export = {
           bucketKey: 'Key'
         });
 
-        const stage2 = new codepipeline.Stage(pipeline, 'S2');
+        const stage2 = new codepipeline.Stage(stack, 'S2', { pipeline });
         new codepipeline.ManualApprovalAction(stack, 'A2', { stage: stage2 });
 
         pipeline.onStateChange('OnStateChange', topic, {
@@ -262,7 +262,7 @@ export = {
         });
 
         const pipeline = new codepipeline.Pipeline(stack, 'Pipeline');
-        const stage = new codepipeline.Stage(pipeline, 'Stage');
+        const stage = new codepipeline.Stage(stack, 'Stage', { pipeline });
         new lambda.PipelineInvokeAction(stack, 'InvokeAction', {
             stage,
             lambda: lambdaFun,
@@ -365,7 +365,7 @@ export = {
 
 function stageForTesting(stack: cdk.Stack): codepipeline.Stage {
     const pipeline = new codepipeline.Pipeline(stack, 'pipeline');
-    return new codepipeline.Stage(pipeline, 'stage');
+    return new codepipeline.Stage(pipeline, 'stage', { pipeline });
 }
 
 function repositoryForTesting(stack: cdk.Stack): codecommit.Repository {
diff --git a/packages/@aws-cdk/aws-lambda/README.md b/packages/@aws-cdk/aws-lambda/README.md
index 759f22beadf86..8956bf1af702c 100644
--- a/packages/@aws-cdk/aws-lambda/README.md
+++ b/packages/@aws-cdk/aws-lambda/README.md
@@ -49,7 +49,9 @@ const lambdaFun = new lambda.Function(this, 'MyLambda', {
 });
 
 const pipeline = new codepipeline.Pipeline(this, 'MyPipeline');
-const lambdaStage = new codepipeline.Stage(pipeline, 'Lambda');
+const lambdaStage = new codepipeline.Stage(this, 'Lambda', {
+    pipeline,
+});
 new lambda.PipelineInvokeAction(this, 'Lambda', {
     stage: lambdaStage,
     lambda: lambdaFun,
diff --git a/packages/@aws-cdk/aws-s3/README.md b/packages/@aws-cdk/aws-s3/README.md
index eaf25155b5b56..a9a5c1bf826dd 100644
--- a/packages/@aws-cdk/aws-s3/README.md
+++ b/packages/@aws-cdk/aws-s3/README.md
@@ -87,7 +87,9 @@ const sourceBucket = new s3.Bucket(this, 'MyBucket', {
 });
 
 const pipeline = new codepipeline.Pipeline(this, 'MyPipeline');
-const sourceStage = new codepipeline.Stage(pipeline, 'Source');
+const sourceStage = new codepipeline.Stage(this, 'Source', {
+    pipeline,
+});
 const sourceAction = new s3.PipelineSource(this, 'S3Source', {
     stage: sourceStage,
     bucket: sourceBucket,