Aws-cdk: Contribution docs are confusing

[SomayaB]

_Originally posted by @nicklaw5 in https://github.com/aws/aws-cdk/pull/5342#issuecomment-574413853_

TBH those contribution docs are very confusing. Some of the scripts it mentions don't exist anymore.

[SomayaB]

Hi @nicklaw5, I'm sorry the contribution docs have been confusing. Would you mind pointing out which areas need some work in your opinion and which scripts don't exist anymore. Hopefully we can make the experience a lot more pleasant this way. Thanks again for contributing, much appreciated! 👍

[nicklaw5]

Here is a summary of the confusions/issues I've encountered while trying to add a missing feature to the @aws-cdk/aws-events-targets.

Scripts and Yarn Commands

Some parts of the docs suggest running shell scripts (eg. pack.sh or build.sh) while others suggest running the equivalent yarn command (eg. yarn pack or yarn build). While there is no difference in terms of what gets executed, this is somewhat confusing and prompts questions such as "Does the yarn command pass additional args or options to the script?".

Some shell scripts (eg. install.sh) exist in the root of the project, while the majority of them exist in the scripts/ directory. That's a little odd and confusing.

Building Packages

For the most part I would think contributors are mainly going to be contributing to individual packages (eg. '@aws-cdk/aws-ecs). I would hope that I don't need to compile every other package just to test the changes added to an individual package. This is especially annoying when running build.sh fails due to an unrelated package failing to compile. Perhaps that's not possible due to the nature of dependencies in this project, but it sure would be nice.

Build Logs and Tests

After pushing a commit, the build logs provided by AWS are sometime unreadable, especially when there are syntax issues in the code. This is because the build logs include the shell colour code in the output. My approach to this was to copy output to my editor and slowly delete the colour codes which eventually pointed me to the error and file the error related to. This was quite annoying.

[SomayaB]

Thanks for the detailed description @nicklaw5. Getting outside contribution is an integral part of the CDK so the feedback is much appreciated. We will update this issue when there is movement.

[DmitryNefedov]

To add to that, it's unclear how to build and test individual package and even more unclear how to build the whole project from scratch.
Would be great to have step by step like:

1. git pull
2. yarn install
3. build.sh ???

etc