chore: document custom action

Signed-off-by: heitorlessa <lessa@amazon.co.uk>

Author: heitorlessa

.github/actions/create-pr/action.yml

@@ -1,11 +1,36 @@
 name: "Create PR custom action"
 description: "Create a PR and a temporary branch, close duplicates"
 
-# This custom action
+# PROCESS
+#
+# 1. Setup git client using Powertools bot username
+# 2. Pushes staged files to a temporary branch
+# 3. Creates a PR from temporary branch against a target branch (typically trunk: develop, main, etc.)
+# 4. Searches for duplicate PRs with the same title
+# 5. If duplicates are found, link to the most recent one, close and delete their branches so we keep a single PR
+# 6. In the event of failure, we delete the now orphaned branch (if any), and propagate the failure
+
+# USAGE
+#
+# - name: Create PR
+#   id: create-pr
+#   uses: ./.github/actions/create-pr
+#   with:
+#     files: "CHANGELOG.md"
+#     temp_branch_prefix: "ci-changelog"
+#     pull_request_title: "chore(ci): changelog rebuild"
+#     github_token: ${{ secrets.GITHUB_TOKEN }}
+# - name: Step to demonstrate how to access outputs (no need for this)
+#   run: |
+#     echo "PR number: ${PR_ID}"
+#     echo "Branch: ${BRANCH}"
+#   env:
+#     PR_ID: ${{ steps.create-pr.outputs.pull_request_id}}
+#     BRANCH: ${{ steps.create-pr.outputs.temp_branch}}
 
 inputs:
   files:
-    description: "Files to add"
+    description: "Files to add separated by space"
     required: true
   temp_branch_prefix:
     description: "Prefix for temporary git branch to be created, e.g, ci-docs"