[FEATURE] Vendor README instructions for modules & combinations.

[JoshuaToth]

Describe the feature

When using several modules in tandem, such as a TypeSafeApiProject, CloudscapeReactTsWebsiteProject and InfrastructureTsProject, generate generic instructions on how you would modify the projects to add a new feature, such as an api endpoint and have it deployed/integrated.

An example of what I usually add into the monorepo level readme for the above combination. Of course my descriptions are a little less formal than what the end result should probably be:

/packages/api

The smithy/typesafe-api code that defines the apigateway -> lambda interfaces.
The only files you should need to edit in here are within packages/api/model/src/main/smithy/operations . everything else is autogenerated on a build.

This part is a little complicated for generating API stuff. But in short. The definitions in here will create types and runtime libraries that can be used elsewhere in the repository, mainly in the website, infra and lambda packages. follow the start-workflow files around and hopefully you get a good idea of how things fit together.

When creating a new method you pretty much need to:

• add into one of the operations folder files, or create a new one
• pdk build, this will generate a lambda file in packages/api/handlers/typescript. The build will also fail because the infra code is initially missing. This is OK.
• The method should be available on the website client library at this point, but not deployed.
• edit the lambda as needed.
• in the packages/infra/src/constructs/api.ts add a new lambda handler for the defined method.
• pdk build should succeed.
• pdk nx run @<package-namespace>/infra:deploy

Use Case

When I use the PDK framework, I often hand over the code to another team that will keep working on the project. A big part of this handover is making sure there is enough documentation in the repository so the new developers can set up, deploy, and modify the monorepo.

The documentation needed is pretty similar every time I hand over a PDK project built like this. Even though there is a lot of documentation available for PDK, the new developers usually haven't read it. My goal is to make the handover smooth by giving them just enough info to quickly understand things and start exploring. I want the documentation to have enough details to get their development environment going, but not overwhelm them with unnecessary stuff. Simple, targeted documentation helps the new team spend time building features instead of figuring out the handover process.

In short, customized README.md docs that help developers easily understand the repository makes PDK code transfers better. This way, the new team can move from taking over the code to delivering new features faster.

Proposed Solution

No response

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

PDK version used

v0.22.49

What languages will this feature affect?

No response

Environment details (OS name and version, etc.)

Mac OS 14.2.1

[agdimech]

This is a great feature request, will definitely get this prioritized :)

[github-actions]

This issue is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon. If you wish to exclude this issue from being marked as stale, add the "backlog" label.

[JoshuaToth]

Bump