notes on the development environment

README.md

@@ -2,6 +2,57 @@ Create and synchronize a PR in a dependent repository
 
 # Hacking
 
+The test environment consists of the following
+
+* A forgejo instance with a runner
+* An unprivileged user user1
+* The repository user1/originrepo
+  * contains a pull_request workflow using cascading-pr that targets user2/destinationrepo
+  * contains a script that will modify user2/destinationrepo
+  * a PR from branch1 to main
+* The repository user1/cascading-pr with the action under test
+* An unprivileged user user2
+* The repository user2/destinationrepo
+
+## testing an update on the action
+
+* run `tests/run.sh --debug` once so all is in place
+* commit changes to the files that are in the cascading-pr action
+  (action.yml, cascading-pr.sh etc.)
+* push the modified action to `user1/cascading-pr`
+* visit $url/user1/originrepo/actions/runs/1 and click re-run
+
+## interactive debugging
+
+Following the steps below recreate the same environment as the
+integration workflow locally. It is helpful for forensic analysis when
+something does not run as expected and the error displayed are unclear.
+
+To help with the development loop all steps are idempotent and
+running `tests/run.sh --debug` multiple times must succeed.
+
+Individual steps can be run independendely by using the name of the function.
+For instance:
+
+* `tests/run.sh --debug create_pull_request` will only call the `create_pull_request`
+  function found in `tests/run.sh` to (re)create the pull request in `user1/originrepo`.
+* `./cascading-pr.sh --debug --origin-url ... upsert_branch` will only call the `upsert_branch`
+  function found in `cascading-pr.sh`.
+
+## directories
+
+The `tests/run.sh` script stores all its files in
+`/tmp/cascading-pr-test`. The temporary directories created by
+`cascading-pr.sh` are disposed of when the script ends.
+
+## logging
+
+If `--debug` is used a full debug log is displayed, very complete and
+very verbose. Otherwise it is stashed in a temporary file and only
+displayed if an error happens.
+
+## snippets for copy/pasting
+
 ```sh
 git clone https://code.forgejo.org/actions/setup-forgejo
 export PATH=$(pwd)/setup-forgejo:$PATH
@@ -16,5 +67,5 @@ url=http://$(cat forgejo-ip):3000
 firefox $url
 tests/run.sh --debug
 tests/run.sh --debug create_pull_request
-cascading-pr.sh --debug --origin-url "$url" --origin-repo "user1/originrepo" --origin-token "$(cat /tmp/cascading-pr-test/user1/repo-token)" --origin-pr 1 --destination-url "$url" --destination-repo "user2/destinationrepo" --destination-token "$(cat /tmp/cascading-pr-test/user2/repo-token)" --destination-branch "main" --update "upgraded"
+./cascading-pr.sh --debug --origin-url "$url" --origin-repo "user1/originrepo" --origin-token "$(cat /tmp/cascading-pr-test/user1/repo-token)" --origin-pr 1 --destination-url "$url" --destination-repo "user2/destinationrepo" --destination-token "$(cat /tmp/cascading-pr-test/user2/repo-token)" --destination-branch "main" --update "upgraded" run
 ```

cascading-pr.sh

@@ -119,7 +119,6 @@ function finalize_options() {
 }
 
 function run() {
-    dependencies
     repo_login ${options[destination_repo]}
     upsert_branch
     upsert_pr
@@ -198,6 +197,8 @@ function main() {
     done
 }
 
+dependencies
+
 if echo "${@}" | grep --quiet -e '--debug' ; then
     main "${@}"
 else