chore: update GH workflows by adding documentation and removing unuse…

…d files

.github/workflows/build-devcontainer-image.yaml

@@ -1,7 +1,14 @@
+#
+# this is a shared workflow that is used by other workflows
+#
+# its primary purpose is to build and push the devcontainer.
+# it returns the image name
+#
+# @see ./release.yaml for how it is used
+#
 name: Build DevContainer Image
 on:
   workflow_call:
-
     # secrets:
     #   GITHUB_TOKEN:
     #     required: true

.github/workflows/release.yaml

@@ -1,3 +1,10 @@
+#
+# this is the release workflow that is triggered by a push to main or develop branches
+# it will
+# - build the project
+# - @TODO: save the artifacts to the workflow
+# - @TODO: create a GitHub releases with changelog and upload the artifacts
+#
 name: 'release'
 
 on: