core: refresh the contributing guide

[pahud]

Describe the feature

The contributing guide has been missing a lot of information since the repo remodel and is getting very difficult for the community to contribute the pull requests. I think we should update the contributing guide to clarify some important steps including:

1. How to build the core package(aws-cdk-lib).
2. How to run yarn watch when we start our hacking on individual module(such as aws-eks).
3. After we modify the source, how to deploy a simple app with our fix in our AWS account to validate it.
4. How to run all unit tests on a specific module(e.g. aws-eks).
5. How to run a specific unit test on a specific module(e.g. aws-eks).
6. How to run all integ tests on specific module(e.g. aws-eks).
7. How to run a specific integ test and update the snapshots on failed.
8. How to run awslint or any other linting tools before submitting the PR.
9. How to avoid common errors such as JavaScript heap out of memory error described in (aws-cdk-lib): Reached heap limit Allocation failed - JavaScript heap out of memory #25092

Use Case

After the repo remodel, contributors now feel confused and the contributing guide is out-of-date.

Proposed Solution

Update the contributing guide with relevant steps and guidance.

Other Information

This is my personal note for a recent PR to aws-eks but I expect a formal guidance.

# in aws-cdk root directory
$ export NODE_OPTIONS=--max-old-space-size=8192
$ yarn install
$ cd packages/aws-cdk-lib
$ ../../scripts/buildup 
# or
$ npx lerna run build --scope=aws-cdk-lib
# now run `yarn watch` in `aws-cdk-lib`
$ yarn watch
# cd to individual module directory and start your hack
$ cd aws-eks
# now, run the unit tests for this individual module
$ yarn test aws-eks
# now validate the existing integ tests in framework-integ
$ cd <cdk_root>/packages/@aws-cdk-testing/framework-integ
# we need buildup first
$ ../../../scripts/buildup 
# now let's run all existing integ tests for aws-eks
$ yarn integ --directory test/aws-eks/test/
# If any single integ test fails, run with `--update-on-failed`. This triggers a real deployment and snapshot update.
$ yarn integ --update-on-failed test/aws-eks/test/integ.xxx.js
# test again without `--update-on-failed`
$ yarn integ test/aws-eks/test/integ.xxx.js
# when we fix all individual integ tests, run against the directory again
$ yarn integ --directory test/aws-eks/test/
# now you should pass all unit tests and integ tests

Acknowledgements

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

CDK version used

v2.72.1

Environment details (OS name and version, etc.)

mac os x

[mattiamatrix]

npx lerna run build --scope=aws-cdk-lib is currently failing for me.

...
100_sam/998_lift_transform_patch.json: AWS::Serverless::LayerVersion: Lift transform version to each resource
100_sam/998_lift_transform_patch.json: AWS::Serverless::SimpleTable: Lift transform version to each resource
100_sam/998_lift_transform_patch.json: AWS::Serverless::StateMachine: Lift transform version to each resource
100_sam/999_cleanup_patch.json: Remove properties that conflict with the CFN spec
spec-source/specification/100_sam
TypeError: Cannot use 'in' operator to search for 'Properties' in undefined
    at Object.isRecordType (/Users/***/Code/GitHub/***/aws-cdk/packages/@aws-cdk/cfnspec/lib/schema/specification.ts:55:22)
    at replaceIncompleteTypes (/Users/***/Code/GitHub/***/aws-cdk/packages/@aws-cdk/cfnspec/build-tools/massage-spec.ts:20:17)
    at massageSpec (/Users/***/Code/GitHub/***/aws-cdk/packages/@aws-cdk/cfnspec/build-tools/massage-spec.ts:6:3)
    at generateResourceSpecification (/Users/***/Code/GitHub/***/aws-cdk/packages/@aws-cdk/cfnspec/build-tools/build.ts:42:14)
    at async main (/Users/***/Code/GitHub/***/aws-cdk/packages/@aws-cdk/cfnspec/build-tools/build.ts:28:5)
error Command failed with exit code 255.

[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.