From 7f524bea1453e9e0a8280d2c5d4285c0aac1a790 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Fri, 13 Oct 2023 23:38:57 +0200 Subject: [PATCH] documentation --- README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ action.yml | 28 ++++++++++++++++++- 2 files changed, 109 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cb49618..5512eda 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,83 @@ Create and synchronize a PR in a dependent repository + +## 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. + + +## 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 | + + +# 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` diff --git a/action.yml b/action.yml index dd028e0..3cab5a9 100644 --- a/action.yml +++ b/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: