chore(codepipeline-actions): change the name of the ServiceCatalogDeployAction #13780

skinny85 · 2021-03-24T23:31:14Z

The ServiceCatalogDeployAction was an experimental Action in the codepipeline-actions module.
Stabilize it by renaming it ServiceCatalogDeployActionBeta1.
Also, remove the unused dependency between this module,
and service catalog module.

BREAKING CHANGE: the Action ServiceCatalogDeployAction has been renamed to ServiceCatalogDeployActionBeta1

codepipeline-actions: the type ServiceCatalogDeployActionProps has been renamed to ServiceCatalogDeployActionBeta1Props

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

gitpod-io · 2021-03-24T23:31:16Z

NetaNir

@skinny85 thank you so much for leading the way on this! I was thinking that real life example will be the best way to decide on a naming scheme.

(summarizing the change in this PR for the sake of discussion)

There is one preview API introduced in this PR, compose of two parts, the method ServiceCatalogDeployActionPreview and it's props that are also named as Preview: ServiceCatalogDeployActionPreviewProps.

In the original RFC we discussed a few requirements for the naming scheme of Preview APIs:

some relevant discussion here

Should include a version indicator, e.g xxx1. This is required so we can introduce additional preview versions before the final version.
Should reflect the experimental nature of the API. The motivation being that while we are not going to introduce a non backward compatible changes, these API are not fully baked, might include bugs and will be deprecated (if only to introduce an identical API under the final name).
Minimal "visual noise" (term stolen from @rix0rrr).

Adding all the above and applying it on the ServiceCatalogDeployAction API, I can think of a few options, please do add alternatives if any comes to mind:

ServiceCatalogDeployActionBeta1 - beta is a good candidate as it is a widely used term and will resonate with users as a "non final version of the API". It does however misses on the "visual noise" aspect.
ServiceCatalogDeployActionX1 - I was on the fence for this one when it was initially suggested, mainly because I thought it will not convey the idea behind the preview APIs concept. But I can see "The AWS CDK X APIs" section in our docs, and it also sound nice, e.g "What are the X APIs?". I think this can be less cumbersome than other options both from a coding perspective and "verbal simplicity" (easier to refer to, I can't think of a better way to phrase this.).
ServiceCatalogDeployActionPre1 - Not sure this one actually adds value over beta. On one hand, Pre is for Preview, so it has the advantage of consistency, on the other hand, Pre does not have the same "familiar concept" advantage of beta . Adding it here in case someone really loves it.

I think Im leaning towards 2, what do you think?

NetaNir · 2021-04-07T05:02:43Z

packages/@aws-cdk/aws-codepipeline-actions/package.json

@@ -90,7 +90,6 @@
    "@aws-cdk/aws-iam": "0.0.0",
    "@aws-cdk/aws-lambda": "0.0.0",
    "@aws-cdk/aws-s3": "0.0.0",
-    "@aws-cdk/aws-servicecatalog": "0.0.0",


skinny85 · 2021-04-07T20:20:13Z

In the original RFC we discussed a few requirements for the naming scheme of Preview APIs:

some relevant discussion here

Should include a version indicator, e.g xxx1. This is required so we can introduce additional preview versions before the final version.

Should reflect the experimental nature of the API. The motivation being that while we are not going to introduce a non backward compatible changes, these API are not fully baked, might include bugs and will be deprecated (if only to introduce an identical API under the final name).

Minimal "visual noise" (term stolen from @rix0rrr).

Adding all the above and applying it on the ServiceCatalogDeployAction API, I can think of a few options, please do add alternatives if any comes to mind:

ServiceCatalogDeployActionBeta1 - beta is a good candidate as it is a widely used term and will resonate with users as a "non final version of the API". It does however misses on the "visual noise" aspect.

ServiceCatalogDeployActionX1 - I was on the fence for this one when it was initially suggested, mainly because I thought it will not convey the idea behind the preview APIs concept. But I can see "The AWS CDK X APIs" section in our docs, and it also sound nice, e.g "What are the X APIs?". I think this can be less cumbersome than other options both from a coding perspective and "verbal simplicity" (easier to refer to, I can't think of a better way to phrase this.).

ServiceCatalogDeployActionPre1 - Not sure this one actually adds value over beta. On one hand, Pre is for Preview, so it has the advantage of consistency, on the other hand, Pre does not have the same "familiar concept" advantage of beta . Adding it here in case someone really loves it.

I think Im leaning towards 2, what do you think?

Thanks for the review @NetaNir. I went with option nr 1. I think ServiceCatalogDeployActionX1 looks weird, and "Beta" is not much more "noise", especially verbally, compared to "X", to justify this more cryptic way of naming.

Submitted a new revision, would appreciate another look!

iliapolo · 2021-04-09T23:47:37Z

I agree that option 3 doesn't really give any additional value.

As far as the other two, while I do like the sound of CDK X API's, I think it's less clear and isn't much of a visual noise reduction over beta. So my vote goes for beta as well.

NetaNir · 2021-04-09T23:50:25Z

I agree with the advantage of clarity for xxxBeta1. But, let me try and pitch the X suffix again: I think it sound better, from a "marketing" perspective. It's easier to refer to: "The X APIs". Its disadvantage of not being an industry wide term can also be viewed as an advantage as it means that there will be no assumption made on what does it mean in the context of the AWS CDK, we get to define it.

skinny85 · 2021-04-12T17:07:54Z

I agree with the advantage of clarity for xxxBeta1. But, let me try and pitch the X suffix again: I think it sound better, from a "marketing" perspective. It's easier to refer to: "The X APIs". Its disadvantage of not being an industry wide term can also be viewed as an advantage as it means that there will be no assumption made on what does it mean in the context of the AWS CDK, we get to define it.

I actually think "X APIs" sound weird, like we're doing R-rated APIs in CDK 🙂. So I don't see their advantage from a marketing perspective.

Talking about "Beta APIs" seems very natural to me in comparison.

NetaNir · 2021-04-15T17:40:46Z

I can't argue with that. beta it is

mergify · 2021-04-15T17:41:13Z

Thank you for contributing! Your pull request will be updated from master and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2021-04-15T18:11:03Z

Thank you for contributing! Your pull request will be updated from master and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

…loyAction The `ServiceCatalogDeployAction` was an experimental Action in the codepipeline-actions module. Stabilize it by renaming it `ServiceCatalogDeployActionPreview`. Also, remove the unused dependency between this module, and service catalog module. BREAKING CHANGE: the Action `ServiceCatalogDeployAction` has been renamed to `ServiceCatalogDeployActionPreview` * **codepipeline-actions**: the type `ServiceCatalogDeployActionProps` has been renamed to `ServiceCatalogDeployActionPreviewProps`

aws-cdk-automation · 2021-04-15T21:56:23Z

AWS CodeBuild CI Report

CodeBuild project: AutoBuildProject89A8053A-LhjRyN9kxr8o
Commit ID: 9ffa948
Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

mergify · 2021-04-15T21:56:43Z

Thank you for contributing! Your pull request will be updated from master and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

…loyAction (aws#13780) The `ServiceCatalogDeployAction` was an experimental Action in the codepipeline-actions module. Stabilize it by renaming it `ServiceCatalogDeployActionBeta1`. Also, remove the unused dependency between this module, and service catalog module. BREAKING CHANGE: the Action `ServiceCatalogDeployAction` has been renamed to `ServiceCatalogDeployActionBeta1` * **codepipeline-actions**: the type `ServiceCatalogDeployActionProps` has been renamed to `ServiceCatalogDeployActionBeta1Props` ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

With the commitment to not support breaking changes in stable modules (and all of aws-cdk-lib), we need to document the standard for introducing APIs we know to be potentially experimental or unstable. This standard was originally proposed in https://github.com/aws/aws-cdk-rfcs/blob/master/text/0249-v2-experiments.md, and was first actually used in #13780. This task documents the standard in the CONTRIBUTING guide so we can use it as a reference going forward. closes #16434

With the commitment to not support breaking changes in stable modules (and all of aws-cdk-lib), we need to document the standard for introducing APIs we know to be potentially experimental or unstable. This standard was originally proposed in https://github.com/aws/aws-cdk-rfcs/blob/master/text/0249-v2-experiments.md, and was first actually used in #13780. This task documents the standard in the CONTRIBUTING guide so we can use it as a reference going forward. closes #16434 ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

With the commitment to not support breaking changes in stable modules (and all of aws-cdk-lib), we need to document the standard for introducing APIs we know to be potentially experimental or unstable. This standard was originally proposed in https://github.com/aws/aws-cdk-rfcs/blob/master/text/0249-v2-experiments.md, and was first actually used in aws#13780. This task documents the standard in the CONTRIBUTING guide so we can use it as a reference going forward. closes aws#16434 ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

skinny85 requested a review from NetaNir March 24, 2021 23:31

github-actions bot added the @aws-cdk/aws-codepipeline-actions label Mar 24, 2021

github-actions bot assigned skinny85 Mar 24, 2021

mergify bot added the contribution/core This is a PR that came from AWS. label Mar 24, 2021

NetaNir reviewed Apr 7, 2021

View reviewed changes

skinny85 force-pushed the fix/service-catalog-deploy-codepipeline-action branch 2 times, most recently from 1b3514f to 27e2cbd Compare April 7, 2021 20:17

skinny85 requested a review from NetaNir April 7, 2021 20:20

skinny85 mentioned this pull request Apr 9, 2021

chore: remove all @experimental annotation #14071

Merged

NetaNir approved these changes Apr 15, 2021

View reviewed changes

skinny85 force-pushed the fix/service-catalog-deploy-codepipeline-action branch from 5a5cdec to 9ffa948 Compare April 15, 2021 21:30

mergify bot merged commit a99e901 into aws:master Apr 15, 2021

skinny85 deleted the fix/service-catalog-deploy-codepipeline-action branch April 15, 2021 21:59

NetaNir mentioned this pull request Apr 21, 2021

feat(ec2): create NAT Gateways with fixed IPs #14250

Merged

nija-at mentioned this pull request Jun 2, 2021

rfc 328 - polyglot assert aws/aws-cdk-rfcs#330

Merged

skinny85 mentioned this pull request Aug 26, 2021

RFC 249: Rewrite the V2 Experiments RFC to have a more working-backwards tone aws/aws-cdk-rfcs#377

Merged

njlynch mentioned this pull request Sep 9, 2021

(docs): Updated guidance for preview APIs #16434

Closed

njlynch mentioned this pull request Sep 30, 2021

docs(CONTRIBUTING): document guidance for preview APIs #16731

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(codepipeline-actions): change the name of the ServiceCatalogDeployAction #13780

chore(codepipeline-actions): change the name of the ServiceCatalogDeployAction #13780

skinny85 commented Mar 24, 2021 •

edited

Loading

gitpod-io bot commented Mar 24, 2021 •

edited

Loading

NetaNir left a comment

NetaNir Apr 7, 2021

skinny85 commented Apr 7, 2021

iliapolo commented Apr 9, 2021

NetaNir commented Apr 9, 2021

skinny85 commented Apr 12, 2021

NetaNir commented Apr 15, 2021

mergify bot commented Apr 15, 2021

mergify bot commented Apr 15, 2021

aws-cdk-automation commented Apr 15, 2021

mergify bot commented Apr 15, 2021

chore(codepipeline-actions): change the name of the ServiceCatalogDeployAction #13780

chore(codepipeline-actions): change the name of the ServiceCatalogDeployAction #13780

Conversation

skinny85 commented Mar 24, 2021 • edited Loading

gitpod-io bot commented Mar 24, 2021 • edited Loading

NetaNir left a comment

Choose a reason for hiding this comment

NetaNir Apr 7, 2021

Choose a reason for hiding this comment

skinny85 commented Apr 7, 2021

iliapolo commented Apr 9, 2021

NetaNir commented Apr 9, 2021

skinny85 commented Apr 12, 2021

NetaNir commented Apr 15, 2021

mergify bot commented Apr 15, 2021

mergify bot commented Apr 15, 2021

aws-cdk-automation commented Apr 15, 2021

AWS CodeBuild CI Report

mergify bot commented Apr 15, 2021

skinny85 commented Mar 24, 2021 •

edited

Loading

gitpod-io bot commented Mar 24, 2021 •

edited

Loading