Improve cdktf upgrade documentation.

[jsteinich]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

Description

There have been a couple tickets that have come in that ended up just being an error in upgrading cdktf. The typescript templates have some information about which commands to run, but not really an explanation of the full process. Other templates don't even have that much.

I'm thinking either a dedicated page or a section within the using the cli page. Possibly linking to it with each version's changelog entry.

Contents to include:

• Updating cdktf-cli / cdktf packages themselves
• Needing to run cdktf get
• Updating package/project files to use newer versions of the libraries for other languages

References

#468

[xiehan]

@jsteinich Do our upgrade guides on https://developer.hashicorp.com/terraform/cdktf/release satisfy this need or is there more you think we should still do here?

[ansgarm]

@xiehan, I'd still see this as an opportunity to improve, as our upgrade guides usually explain the changes and how to adjust for them, but not how to upgrade cdktf itself in the first place in general (e.g. by changing the dependency version, running npm install, and optionally re-running cdktf get).

[jsteinich]

@jsteinich Do our upgrade guides on https://developer.hashicorp.com/terraform/cdktf/release satisfy this need or is there more you think we should still do here?

I agree with everything that @ansgarm stated. The most common issue that I've seen here is updating the cli without updating the cdktf library or vice versa. Re-running cdktf get has become less of an issue since there are pre-built providers and fewer breaking changes, but it does still come up.

[zeph]

@xiehan I'd really love to be more constructive on detailing what's wrong with the upgrade procedure... but it is the 3rd time in 2years that I pick up a cdktf project from a git repo, from colleagues, with an outdated stack. This time too, I'll simply nuke the whole setup and leave it be. I quote how my colleague tried to describe the upgrade process to me:

Basically it is try and error. You start with the offocial cli. If this does not work, you try to update manually the deps in the package.json. If this does not work, then you remove package.json, do an init, reinstall all the libs you need so that they automatically resource their deps from scratch and Then finally you can start changing your Code

The third method is the most sure to work, but the it is the longest too

This cannot be, it simply leads to frustration and insane amount of wasted hours of manual attempts of changes

I really hope such documentation gets improved with a step by step guide for someone that stumbles on project that require nodejs 14.x and related dependencies... that's the picture of the market in my personal bubble (given the low engagement on this ticket, it is probably just my own issue)