Multiple meanings of "hot-reload" - sometimes from "src" dir, sometimes from "build" dir

[pete-heirendt-vacasa]

Description

The 1st meaning, when using Python or Node, many users interpret "hot-reload" to mean that if you edit your source code, then sam local start-api will pick up that code change without you also having to do a sam build (that is the common definition among these non-compiled languages).

A 2nd meaning of "hot-reload" is that you do have to re-build after every code change, but you do not have to restart sam local start-api. This meaning was explained in following issue:

• "sam local start-api" uses .aws-sam directory without warning #1211 - "sam local start-api" uses .aws-sam directory without warning

Causing some confusion is that in reality both definitions can be observed -- the behavior of sam local start-api changes depending on whether or not the ".aws-sam/build" directory exists (the docs do not yet make any mention of this though).

• Behavior 1 - As described in first paragraph above, that is in fact the exact behavior for sam local start-api if you have never done a sam build (or if you manually deleted the ".aws-sam/build" directory). Also note that output from sam local start-api has one line saying this:
  • Mounting /XXXX/src as /var/task:ro,delegated inside runtime container
• Behavior 2 - Without much notice to the user, the behavior will change if you ever do a sam build. At that point sam local start-api changes to only load from the ".aws-sam/build" directory. (There is a small indication to the user: as mentioned in below steps, there is one line output by sam local start-api that mentions Mounting ... inside runtime container.) Also note that output from sam local start-api has one line saying this:
  • Mounting /XXXX/.aws-sam/build/Function2a as /var/task:ro,delegated inside runtime container

Steps to reproduce

1. Delete the ".aws-sam/build" directory
2. Run sam local start-api
   1. Hit your Lambda's API
   2. Make a code change to your Lambda
   3. Hit your Lambda's API again
   4. Result: Code changes take effect without having to also do a sam build. Also note that output from sam local start-api has one line saying this:
      1. Mounting /XXXX/src as /var/task:ro,delegated inside runtime container
3. Stop the above sam local start-api
4. Do a sam build
5. Repeat the above starting at step 2.
   1. Result: Code changes now require also doing a sam build after each code change. Also note that output from sam local start-api has one line saying this:
      1. Mounting /XXXX/.aws-sam/build/Function2a as /var/task:ro,delegated inside runtime container

Observed result

The change in behavior is very unexpected, since the documentation pages do not yet have any mention of this detail:

• https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-start-api.html
• https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-start-api.html

Expected result

Would be great to have some mention of these two behaviors in the above docs pages.

Additional environment details (Ex: Windows, Mac, Amazon Linux etc)

1. OS: Mac OSX 10.15 (Catalina)
2. sam --version: SAM CLI, version 0.41.0

[pete-heirendt-vacasa]

Also note that the example animation on this doc page is demonstrating the 1st meaning/behavior above (that you can edit your code and see it run without having to do a sam build):

• https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-start-api.html

I also learned that this will probably not work if you have any dependencies in your requirements.txt (Python), since those dependencies will not exist in your source directory.