Skip to content

quickstart.md

Latest commit

 

History

History
132 lines (98 loc) · 3.72 KB

quickstart.md

File metadata and controls

132 lines (98 loc) · 3.72 KB
Raw

Two Minute Quickstart

Use this path when you want to see whether Maintainer Radar helps a repository before changing any maintainer workflow.

No Install Preview

For a public GitHub repository, open the browser preview and replace the query with your repository:

https://jackspiece.github.io/maintainer-radar/?repo=owner/repo

The browser preview uses public pull request metadata. It does not ask for a GitHub token, does not post comments, and does not install anything.

First GitHub Action Run

For a real maintainer queue report, generate the config and workflow:

maintainer-radar init-repo --profile balanced

This writes .maintainer-radar.json and .github/workflows/maintainer-radar.yml. It refuses to overwrite existing files unless you pass --force.

Or add this workflow manually and run it from the Actions tab:

{% raw %}

name: Maintainer Radar

on:
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: read

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
      - uses: JackSpiece/maintainer-radar@v0.20.0
        id: radar
        env:
          GH_TOKEN: ${{ github.token }}
        with:
          repository: ${{ github.repository }}
          format: markdown
          hydrate: true
          sort: action
          review-plan-minutes: 60

{% endraw %}

Open the Action run summary after it finishes. The summary should show:

  • queue-headline: the one-line state of the PR queue
  • attention-level: whether the queue is blocked, needs follow-up, needs triage, is ready for review, or is quiet
  • workflow-mode: the suggested maintainer workflow for the next pass
  • next-session-brief: what fits in the next 60 minutes

The workflow is read-only. It does not approve, reject, merge, label, or comment.

Optional Repo Tuning

Generate a config file when your repository needs stricter or looser queue thresholds:

maintainer-radar init-config --profile strict --path .maintainer-radar.json
maintainer-radar init-config --profile large-repo --path .maintainer-radar.json

Use strict for smaller projects where large diffs should be flagged earlier. Use large-repo for high-volume repositories where bigger PRs and longer quiet windows are normal. Pass --force only when you want to overwrite an existing config.

First CLI Run

Install from GitHub if you want to test locally:

python -m pip install "git+https://github.com/JackSpiece/maintainer-radar.git"

Then paste a repository URL:

maintainer-radar recommend https://github.com/owner/repo/pulls
maintainer-radar repo https://github.com/owner/repo/pulls --hydrate --sort action --summary-only

Or inspect one pull request:

maintainer-radar pr https://github.com/owner/repo/pull/123

Live CLI scans use the GitHub CLI for authenticated GitHub API access:

gh auth login

What To Do With The First Report

Use the report to choose one concrete maintainer session:

  • Run maintainer-radar recommend owner/repo when you only want the next workflow, attention level, and exact follow-up commands.
  • If attention-level is blocked, clear CI failures, conflicts, stale branch state, or unresolved maintainer blockers first.
  • If workflow-mode is review-sprint, review the highest-score PRs while they are still small and active.
  • If workflow-mode is author-follow-up, send edited follow-up asks instead of starting deep review.
  • If attention-level is quiet, leave the workflow scheduled and avoid checking the queue by hand.

For scheduled workflows and notification gates, see Attention Workflows and GitHub Action Usage.