adjust README to include notes on Makefiles and the CI (#209)

* adjust README to include notes on Makefiles and the CI

* fix header link

* fix header link

* clarify test-ci target

* fix formatting

* fix formatting

* fix formatting

Author: baermat

README.md

@@ -71,3 +71,52 @@ git pull origin master
 ```
 
 The above commands use `sparse-checkout` to only pull the sample you are interested in. You can find the name of the sample directory in the table above.
+
+# Developer Notes
+
+## Makefiles for samples
+All samples should have a Makefile to unify the execution of the otherwise heterogeneous samples.
+It needs to fulfill two criteria:
+- The sample should be executable independently, since it can be checked out on its own (see [Checking out a single sample](#checking-out-a-single-sample)).
+- It should contain a `test-ci` target to be executed automatically within the CI pipeline. This step needs to take care of all infrastructure tasks (starting/stopping/logs/etc) in addition to any sample commands executed.
+
+A typical Makefile looks like this:
+```bash
+export AWS_ACCESS_KEY_ID ?= test
+export AWS_SECRET_ACCESS_KEY ?= test
+export AWS_DEFAULT_REGION=us-east-1
+SHELL := /bin/bash
+
+usage:       ## Show this help
+        @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
+
+install:     ## Install dependencies
+        @which localstack || pip install localstack
+        @which awslocal || pip install awscli-local
+        ## install whatever else you need, like node modules, python packages, etc.
+        @test -e node_modules || npm install
+        @test -e .venv || (python3 -m venv .venv; source .venv/bin/activate; pip install -r requirements.txt)
+
+run:         ## Run the actual sample steps/commands. This assumes LocalStack is up and running.
+        ./run.sh
+
+start:       ## Start LocalStack in detached mode
+        localstack start -d
+
+stop:        ## Stop the Running LocalStack container
+        @echo
+        localstack stop
+
+ready:       ## Make sure the LocalStack container is up
+        @echo Waiting on the LocalStack container...
+        @localstack wait -t 30 && echo LocalStack is ready to use! || (echo Gave up waiting on LocalStack, exiting. && exit 1)
+
+logs:        ## Save the logs in a separate file, since the LS container will only contain the logs of the last sample run.
+        @localstack logs > logs.txt
+
+test-ci:     ## Execute the necessary targets in the correct order for an automatic execution. 
+        make start install ready run; return_code=`echo $$?`;\
+        make logs; make stop; exit $$return_code;
+
+.PHONY: usage install run start stop ready logs test-ci
+```