documentation

README.md

@@ -1,5 +1,83 @@
 Create and synchronize a PR in a dependent repository
 
+<!-- action-docs-description -->
+## Description
+
+
+When used in a workflow triggered by a PR event, it will create,
+update and close a matching PR in another repository. Whenever the
+matching PR is modified by `cascading-pr`, it waits for the CI to
+pass otherwise it fails.
+
+As an example, when a PR is created in
+[`forgejo/runner`](https://code.forgejo.org/forgejo/runner/), a
+matching PR is created in
+[`actions/setup-forgejo`](https://code.forgejo.org/actions/setup-forgejo/)
+with the proposed change. `cascading-pr` will wait until the CI in
+`actions/setup-forgejo` is successful. When the PR in
+`forgejo/runner` is merged, the matching PR in
+`actions/setup-forgejo` is updated to use what was just merged and
+is ready to be reviewed.
+
+The `update` script is expected to be found in the checked out repository
+running the PR. It is given three arguments:
+
+  * A directory in which the destination repository is checked-out
+  * A file with the JSON describing the pull request in the
+    destination repository
+  * A file with the JSON describing the pull request in the
+    origin repository
+
+If changes are found in the destination repository directory, they will be
+pushed as a new commit in the PR.
+<!-- action-docs-description -->
+<!-- action-docs-inputs -->
+## Inputs
+
+| parameter | description | required | default |
+| --- | --- | --- | --- |
+| origin-url | URL of the Forgejo instance where the PR that triggers the action is located (e.g. https://code.forgejo.org) | `true` |  |
+| origin-repo | the repository in which the PR was created | `true` |  |
+| origin-token | a token with write permission on origin-repo | `true` |  |
+| origin-pr | number of the PR in {orign-repo} | `true` |  |
+| destination-url | URL of the Forgejo instance where the cascading PR is created or updated (e.g. https://code.forgejo.org) | `true` |  |
+| destination-repo | the repository in which the cascading PR is created or updated | `true` |  |
+| destination-branch | the base branch of the destination repository for the cascading PR | `true` |  |
+| destination-token | a token with write permission on destination-repo | `true` |  |
+| update | path to the script to update the content of the cascading PR | `true` |  |
+| prefix | prefix of the cascading PR created on destination-repo (default to {origin-repo}) | `false` |  |
+| verbose | if true print verbose information | `false` | false |
+| debug | if true print debug information | `false` | false |
+<!-- action-docs-inputs -->
+
+# Example
+
+```yaml
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - closed
+
+jobs:
+  test:
+    runs-on: docker
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cascading-pr@v1
+        with:
+          origin-url: https://code.forgejo.org
+          origin-repo: forgejo/lxc-helpers
+          origin-token: ${{ secrets.ORIGIN_TOKEN }}
+          origin-pr: ${{ github.event.pull_request.number }}
+          destination-url: https://code.forgejo.org
+          destination-repo: forgejo/actd
+          destination-branch: main
+          destination-token: ${{ secrets.DESTINATION_TOKEN }}
+          update: ./upgrade-lxc-helpers
+```
+
 # Hacking
 
 The test environment consists of the following (all users password is admin1234)
@@ -74,3 +152,7 @@ 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" run
 ```
+
+## Update the README
+
+With https://github.com/npalm/action-docs `action-docs --update-readme`

action.yml

@@ -2,7 +2,33 @@
 name: 'Cascading PR'
 author: 'Forgejo authors'
 description: |
-  Create and update a PR in another repository
+
+  When used in a workflow triggered by a PR event, it will create,
+  update and close a matching PR in another repository. Whenever the
+  matching PR is modified by `cascading-pr`, it waits for the CI to
+  pass otherwise it fails.
+
+  As an example, when a PR is created in
+  [`forgejo/runner`](https://code.forgejo.org/forgejo/runner/), a
+  matching PR is created in
+  [`actions/setup-forgejo`](https://code.forgejo.org/actions/setup-forgejo/)
+  with the proposed change. `cascading-pr` will wait until the CI in
+  `actions/setup-forgejo` is successful. When the PR in
+  `forgejo/runner` is merged, the matching PR in
+  `actions/setup-forgejo` is updated to use what was just merged and
+  is ready to be reviewed.
+
+  The `update` script is expected to be found in the checked out repository
+  running the PR. It is given three arguments:
+
+    * A directory in which the destination repository is checked-out
+    * A file with the JSON describing the pull request in the
+      destination repository
+    * A file with the JSON describing the pull request in the
+      origin repository
+
+  If changes are found in the destination repository directory, they will be
+  pushed as a new commit in the PR.
 
 inputs:
   origin-url: