Deprecations don't seem to be consistently documented well

[jmm]

Hello,

Deprecations don't seem to be consistently documented well.

At least twice today I've come across deprecation icons where there appears to be zero information about why the functionality is deprecated or what should be used instead.

For example, @aws-cdk/aws-lambda :: class Function (construct) :: addVersion().

Furthermore, there's no reference to that method in the changelog, or even an issue or pull request title including the name.

(Please note that despite all of that, I've seen #5334 and #6771)

---

This is a 📕 documentation issue

[joehillen]

I've noticed the deprecation warning today as well. There is also currentVersionOptions which seems to call lambda.addVersion() but that property doesn't even have a deprecation warning.

The suggested alternative doesn't even work for all cases because you can't use aliases with Lambda@Edge functions.

[jmm]

@joehillen Thanks for weighing in. I think the idea is that currentVersionOptions will feed into version creation for you when it's automatically detected that a new version is necessary. So that part probably makes sense. But it would be good for the documentation to explain why things are deprecated, in this case why you shouldn't / don't need to call addVersion() manually.

It's tangential, but I was looking at that method when trying to figure out why I was getting an error related to version creation -- which seems to be because the automated detection has a false positive in a certain case and is too eager.

Unfortunately I don't have any context on the issue regarding Lambda@Edge functions, so not sure how that fits in.

[joehillen]

I've also hit the problem in your linked issue with the new EdgeFunction construct which is what lead me to find this issue.

[rix0rrr]

We used to not properly surface the recommended replacements for deprecated messages in the documentation.

This has been fixed:

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.