docs: suggest running commands in parallel in action (#1758)

MarcoIeni · Oct 9, 2024 · c664c88 · c664c88
1 parent b8a68d5
commit c664c88
Show file tree

Hide file tree

Showing 9 changed files with 244 additions and 225 deletions.
diff --git a/.github/workflows/release-plz.yml b/.github/workflows/release-plz.yml
@@ -11,7 +11,7 @@ on:
 
 jobs:
   release-plz-release:
-    name: Release-plz Release
+    name: Release-plz release
     runs-on: ubuntu-24.04
     steps:
       # Generating a GitHub token, so that PRs and tags created by
@@ -30,11 +30,12 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
         uses: MarcoIeni/release-plz-action@main
+        with:
+          command: release
         env:
           GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-        with:
-          command: release
+
   release-plz-pr:
     name: Release-plz PR
     runs-on: ubuntu-24.04
@@ -59,8 +60,8 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
         uses: MarcoIeni/release-plz-action@main
+        with:
+          command: release-pr
         env:
           GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
-        with:
-          command: release-pr
diff --git a/crates/release_plz/src/init/mod.rs b/crates/release_plz/src/init/mod.rs
@@ -119,8 +119,24 @@ on:
       - {branch}
 
 jobs:
-  release-plz:
-    name: Release-plz
+  release-plz-release:
+    name: Release-plz release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - name: Run release-plz
+        uses: MarcoIeni/[email protected]
+        with:
+          command: release
+        env:
+          GITHUB_TOKEN: ${{{{ secrets.{github_token} }}}}
+          CARGO_REGISTRY_TOKEN: ${{{{ secrets.{CARGO_REGISTRY_TOKEN} }}}}
+
+  release-plz-pr:
+    name: Release-plz PR
     runs-on: ubuntu-latest
     concurrency:
       group: release-plz-${{{{ github.ref }}}}
@@ -134,6 +150,8 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
         uses: MarcoIeni/[email protected]
+        with:
+          command: release-pr
         env:
           GITHUB_TOKEN: ${{{{ secrets.{github_token} }}}}
           CARGO_REGISTRY_TOKEN: ${{{{ secrets.{CARGO_REGISTRY_TOKEN} }}}}
@@ -179,8 +197,24 @@ mod tests {
                   - main
 
             jobs:
-              release-plz:
-                name: Release-plz
+              release-plz-release:
+                name: Release-plz release
+                runs-on: ubuntu-latest
+                steps:
+                  - name: Checkout repository
+                    uses: actions/checkout@v4
+                  - name: Install Rust toolchain
+                    uses: dtolnay/rust-toolchain@stable
+                  - name: Run release-plz
+                    uses: MarcoIeni/[email protected]
+                    with:
+                      command: release
+                    env:
+                      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                      CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+              release-plz-pr:
+                name: Release-plz PR
                 runs-on: ubuntu-latest
                 concurrency:
                   group: release-plz-${{ github.ref }}
@@ -194,6 +228,8 @@ mod tests {
                     uses: dtolnay/rust-toolchain@stable
                   - name: Run release-plz
                     uses: MarcoIeni/[email protected]
+                    with:
+                      command: release-pr
                     env:
                       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
                       CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

diff --git a/website/docs/extra/busy-repos.md b/website/docs/extra/busy-repos.md
diff --git a/website/docs/github/advanced.md b/website/docs/github/advanced.md
@@ -10,19 +10,13 @@ If your repository uses git submodules, set the `submodules` option in the `acti
 For example:
 
 ```yaml
-jobs:
-  release-plz:
-    name: Release-plz
-    runs-on: ubuntu-latest
-    concurrency:
-      group: release-plz-${{ github.ref }}
-      cancel-in-progress: false
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          submodules: recursive # <-- Add this line
+steps:
+  - name: Checkout repository
+    uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+# highlight-next-line
+      submodules: recursive
 ```
 
 To learn more, see GitHub [docs](https://github.com/actions/checkout/).
@@ -55,21 +49,22 @@ If you want to run other checks before releasing (e.g. `cargo test`), you have t
    ```yml
    jobs:
      release-plz:
-       name: Release-plz
+       name: Release-plz release
        runs-on: ubuntu-latest
        concurrency:
          group: release-plz-${{ github.ref }}
          cancel-in-progress: false
        steps:
          - name: Checkout repository
            uses: actions/checkout@v4
-           with:
-             fetch-depth: 0
          - name: Install Rust toolchain
            uses: dtolnay/rust-toolchain@stable
+   # highlight-next-line
          - run: cargo test # <-- put any check you like here
          - name: Run release-plz
            uses: MarcoIeni/[email protected]
+           with:
+             command: release
            env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
@@ -112,9 +107,27 @@ jobs:
           else
             echo "No open release PR"
           fi
-      - name: Run release-plz
+      - name: Run release-plz PR
         uses: MarcoIeni/[email protected]
+        with:
+          command: release-pr
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
 ```
+
+## Run on schedule
+
+The [quickstart](./quickstart.md) guide configures release-plz to run every time you merge a
+commit to the `main` branch.
+
+To run release-plz periodically, you can use the
+[`schedule`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule) event:
+
+```yaml
+# Trigger the workflow every Monday.
+on:
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    - cron:  '0 0 * * MON'
+```
diff --git a/website/docs/github/output.md b/website/docs/github/output.md
@@ -1,6 +1,6 @@
 # Output
 
-After the action runs, it outputs the following properties:
+When the action runs with `command: release-pr`, it outputs the following properties:
 
 - `prs`: The release PRs opened by release-plz.
   It's an array of objects with the properties of `pr`.
@@ -12,6 +12,10 @@ After the action runs, it outputs the following properties:
     It is the default branch of the repository. E.g. `main`.
   - `html_url`: The URL of the PR.
   - `number`: The number of the PR.
+- `prs_created`: Whether release-plz created any release PR. *Boolean.*
+
+When the action runs with `command: release`, it outputs the following properties:
+
 - `releases`: The JSON output of the `release` command.
   It's an array of JSON objects with the following properties:
   - `package_name`: The name of the package that was released.
@@ -24,44 +28,37 @@ After the action runs, it outputs the following properties:
     [git_tag_enable](../config.md#the-git_tag_enable-field) set to `false`, so that
     you can use this to create the git tag yourself.
   - `version`: The version of the package that was released.
-- `prs_created`: Whether release-plz created any release PR. *Boolean.*
 - `releases_created`: Whether release-plz released any package. *Boolean.*
 
 ## Example: read the output
 
 ```yaml
 jobs:
-  test:
+
+  release-plz-release:
+    name: Release-plz release
     runs-on: ubuntu-latest
-    concurrency:
-      group: release-plz-${{ github.ref }}
-      cancel-in-progress: false
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
+# highlight-next-line
         id: release-plz # <--- ID used to refer to the outputs. Don't forget it.
         uses: MarcoIeni/[email protected]
+        with:
+          command: release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
       - name: Read release output
         env:
           RELEASES: ${{ steps.release-plz.outputs.releases }}
-          PRS: ${{ steps.release-plz.outputs.prs }}
-          PR: ${{ steps.release-plz.outputs.pr }}
-          PRS_CREATED: ${{ steps.release-plz.outputs.prs_created }}
           RELEASES_CREATED: ${{ steps.release-plz.outputs.releases_created }}
         run: |
           set -e
           echo "releases: $RELEASES" # example: [{"package_name":"my-package","prs":[{"html_url":"https://github.com/user/proj/pull/1439","number":1439}],"tag":"v0.1.0","version":"0.1.0"}]
-          echo "prs: $PRS" # example: [{"base_branch":"main","head_branch":"release-plz-2024-05-01T20-38-05Z","html_url":"https://github.com/MarcoIeni/rust-workspace-example/pull/198","number":198}]
-          echo "pr: $PR" # example: {"base_branch":"main","head_branch":"release-plz-2024-05-01T20-38-05Z","html_url":"https://github.com/MarcoIeni/rust-workspace-example/pull/198","number":198}
-          echo "prs_created: $PRS_CREATED" # example: true
           echo "releases_created: $RELEASES_CREATED" # example: true
 
           # get the number of releases with jq
@@ -90,6 +87,39 @@ jobs:
               echo "released $package_name"
           done
 
+  release-plz-pr:
+    name: Release-plz PR
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release-plz-${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - name: Run release-plz
+# highlight-next-line
+        id: release-plz # <--- ID used to refer to the outputs. Don't forget it.
+        uses: MarcoIeni/[email protected]
+        with:
+          command: release-pr
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+      - name: Read release-pr output
+        env:
+          PRS: ${{ steps.release-plz.outputs.prs }}
+          PR: ${{ steps.release-plz.outputs.pr }}
+          PRS_CREATED: ${{ steps.release-plz.outputs.prs_created }}
+        run: |
+          set -e
+          echo "prs: $PRS" # example: [{"base_branch":"main","head_branch":"release-plz-2024-05-01T20-38-05Z","html_url":"https://github.com/MarcoIeni/rust-workspace-example/pull/198","number":198}]
+          echo "pr: $PR" # example: {"base_branch":"main","head_branch":"release-plz-2024-05-01T20-38-05Z","html_url":"https://github.com/MarcoIeni/rust-workspace-example/pull/198","number":198}
+          echo "prs_created: $PRS_CREATED" # example: true
+
           echo "pr_number: ${{ fromJSON(steps.release-plz.outputs.pr).number }}"
           echo "pr_html_url: ${{ fromJSON(steps.release-plz.outputs.pr).html_url }}"
           echo "pr_head_branch: ${{ fromJSON(steps.release-plz.outputs.pr).head_branch }}"
@@ -112,7 +142,7 @@ configuration field.
 
 ```yaml
 jobs:
-  test:
+  release-plz-pr:
     runs-on: ubuntu-latest
     concurrency:
       group: release-plz-${{ github.ref }}
@@ -125,8 +155,11 @@ jobs:
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
+# highlight-next-line
         id: release-plz # <--- ID used to refer to the outputs. Don't forget it.
         uses: MarcoIeni/[email protected]
+        with:
+          command: release-pr
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
@@ -173,7 +206,7 @@ You can commit files to the release PR opened by release-plz.
 
 ```yaml
 jobs:
-  test:
+  release-plz-pr:
     runs-on: ubuntu-latest
     concurrency:
       group: release-plz-${{ github.ref }}
@@ -186,8 +219,11 @@ jobs:
       - name: Install Rust toolchain
         uses: dtolnay/rust-toolchain@stable
       - name: Run release-plz
+# highlight-next-line
         id: release-plz # <--- ID used to refer to the outputs. Don't forget it.
         uses: MarcoIeni/[email protected]
+        with:
+          command: release-pr
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}