aws / aws/aws-pdk

[FEATURE] Vendor README instructions for modules & combinations.

Open
#681 3 comments 2 reactions 0 assignees View on GitHub
backlog feature-request needs-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.