[FEATURE] Vendor README instructions for modules & combinations.
- Dominant language
- TypeScript
- Stars
- 451
- Forks
- 84
- Avg merge
- 20h 3m
- Merged PRs (30d)
- 1
Description
### 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 @/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
Contributor guide
Research direction
Start by reviewing the README.md handover example and the named paths under packages/api/model/src/main/smithy/operations, packages/api/handlers/typescript, and packages/infra/src/constructs/api.ts. Check the pdk build and pdk nx run /infra:deploy flow; done means module combinations produce targeted setup, deployment, and feature-modification instructions for the receiving team.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, typescript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100