feat(codepipeline): final form of the CodeBuild Pipeline action

[skinny85]

BREAKING CHANGE: the output and extraOutputs properties of the CodeBuildAction were merged into one property outputs.

---

Pull Request Checklist

• Testing
  • Unit test added (prefer not to modify an existing test, otherwise, it's probably a breaking change)
  • CLI change?: coordinate update of integration tests with team
  • cdk-init template change?: coordinated update of integration tests with team
• Docs
  • jsdocs: All public APIs documented
  • README: README and/or documentation topic updated
  • Design: For significant features, design document added to design folder
• Title and Description
  • Change type: title prefixed with fix, feat and module name in parens, which will appear in changelog
  • Title: use lower-case and doesn't end with a period
  • Breaking?: last paragraph: "BREAKING CHANGE: <describe what changed + link for details>"
  • Issues: Indicate issues fixed via: "Fixes #xxx" or "Closes #xxx"
• Sensitive Modules (requires 2 PR approvers)
  • IAM Policy Document (in @aws-cdk/aws-iam)
  • EC2 Security Groups and ACLs (in @aws-cdk/aws-ec2)
  • Grant APIs (only if not based on official documentation with a reference)

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.

[eladb]

I am failing to understand why we continuously make this API less ergonomic. This change goes against our design tenet to optimize for the common case. I’d argue that 99% of pipeline actions would have a single output. Can you please provide the motivation for this change?

[rix0rrr]

When given the choice between:

interface {
  things: string[];
}

And:

interface {
  thing: string;

  moreThings?: string[];
}

I would also prefer the first one. Why would you purpose introduce that kind of shape irregularity on purpose?

For one thing, the convenience argument assumes it will always be a human supplying the input values, and they will trivially be able to pick the right argument.

At the same time, it makes it harder on any kind of automated or higher-level code, which for example might read the list of artifacts from a JSON file, or gets it from a service call (to name something)[1].

I made the same mistake with CompositePrincipal, and immediately a user complained because they had to jump through hoops to add a higher-level abstraction over it: #2327

Given that the cost is having to type an additional [ ], I don't think it's too bad.

[1] Pre-emptive response to "you can just pick off the first element and pass it into another field": yes, but you're introducing more busywork and chance of error. In a different but related typical programming example, you can also return null instead of an empty list but now you're making other people type ifs everywhere in order to deal with your special case that didn't need to be a special case. My opinion is that every design decision that leads to the addition of ifs that didn't need to be there, is wrong, since it increases chances of human fuck-up.

Yes, that means I will take element.setVisible(true|false) over element.show() and element.hide(), and that's a hill I'm willing to die on :P.

[eladb]

it’s all about API ergonomics. If in 99% of the cases actions will have a single output, having to pass in an array is less comfortable. In some languages (ahm java) it’s even annoying. We should constantly think about the common case and optimize for it.

If this was the only case, then okay, but I feel we have been continuously making our pipelines API less ergonomic (artifacts, etc) and I wanted to call out that this is not the right direction.

The CDK is all about the developer experience. More verbosity and ceremony creates friction and redundant boilerplate for customers, and we should avoid them as much as possible.

I am curious what is the motivation behind this change.

[eladb]

I've given it some thought and I am fine with this. I feel we will need to build some L3s for pipelines anyway, and we'll make all our ergonomics dreams come true at that layer.

[skinny85]

Rebased to solve conflicts.