repo-radar은(는) 무엇을 하나요?
대시보드는 하나의 HTML 파일로, scripts/dashboard.py가 GitHub에서 데이터를 가져와 만듭니다.
Python 3.10+, PyYAML, GitHub CLI(gh)가 설치되어 있고 로그인되어 있어야 합니다.
AI를 호출하지 않으므로 GitHub Actions에서 매일 아침 무료로 다시 빌드할 수 있습니다.
탭:
| 탭 | 표시 내용 |
|---|---|
| 플랜(Plan) | 저장소에 플랜 파일이 있을 때만 표시됩니다. 시스템의 모든 부분을 박스로 나타내고, 각 부분의 소유자, 빌드됨/리뷰 중/누락 상태를 보여줍니다. PR이 머지되거나 닫힌 항목과, 어떤 항목도 가리키지 않는 열린 PR을 표시합니다. |
| 풀 리퀘스트(Pull requests) | 필요한 작업별로 정렬된 열린 PR: 머지 준비 완료, 리뷰 필요, 작성자 대기, 체크 실패, 드래프트. "여기서 시작"은 최대 5개를 선택합니다. |
| 이슈(Issues) | 열린 이슈: 아무도 할당되지 않음, 누군가 할당됨, PR이 열려 있음. |
| 그래프(Graph) | 열린 작업의 연결 관계: 플랜 박스 → 이슈 → PR, 하위 이슈, "차단됨", 다른 PR의 브랜치를 기반으로 한 PR. |
| 완료(Done) | 지난 90일 동안 닫힌 PR과 이슈, 그리고 이를 포함한 릴리스. |
설정 방법은 두 가지입니다. 명확하지 않으면 사용자에게 어떤 방식을 원하는지 물어보세요:
| 방식 | 대상 | 추가되는 내용 및 위치 |
|---|---|---|
단일 저장소 (init) | 해당 저장소에서 작업하는 사람 | 해당 저장소에 일일 Action 추가, 해당 저장소의 페이지 빌드 |
워치 리스트 (init --watch) | 여러 저장소를 모니터링하는 관리자나 교사 | 자신의 저장소 중 하나에 일일 Action 추가, 각 감시 저장소의 페이지 + 개요 페이지 빌드. 감시 대상 저장소에는 아무것도 추가되지 않음 |
SCRIPT는 이 스킬 폴더의 scripts/dashboard.py 또는 init을 실행한 저장소의 .github/dashboard/dashboard.py를 의미합니다.
플랜 파일 (선택 사항)
플랜은 시스템에 필요한 것을 나열하며, GitHub가 알 수 없는 부분(아직 이슈나 PR이 열리지 않은 부분)을 포함합니다. 전체 형식은 scripts/dashboard_plan.py 상단에 있으며, templates/plan.yaml은 시작 템플릿입니다. 간단히 말해: 박스들의 그룹, 각 박스는 항목 리스트, 각 항목은 built, simulated, pr (번호 포함), 또는 missing입니다. 박스에는 owner가 있거나 그룹의 소유자를 따릅니다. 기본 위치는 docs/plan.yaml이며, 다른 경로를 사용하려면 --plan을 전달하세요.
규칙
- 보고 먼저, 요청 시에만 수정. 스크립트는 절대 플랜을 수정하지 않습니다. 사용자가 PR을 플랜에 올려달라고 요청할 때만 수정하세요.
- 사용자 자신의 항목만 수정. 다른 사람의 항목과
as_of줄은 그대로 둡니다. 여러 사람이 동시에 같은 줄을 수정하지 않도록 합니다. - 사용자가 주간 리프레시를 실행하지 않으면 항목을
built로 표시하지 마세요. 한 사람이 PR이 머지된 후 일주일에 한 번 수행합니다. 대신 "머지되었습니다. 주간 리프레시 준비가 되었습니다."라고 말하세요. - 상태를 임의로 만들지 마세요. 열린 PR이 해당 작업을 수행할 때만 항목은
pr입니다. PR이 어떤 박스에 속하는지 알 수 없으면 물어보세요. - HTML 페이지를 메인 브랜치에 커밋하지 마세요. 일일 Action은 자체
dashboard브랜치에 유지합니다. 수동으로 빌드한 페이지는 저장소 외부의 임시 폴더(<scratch dir>)에 저장됩니다.
저장소에 설정
한 번에 물어보세요, 아무것도 쓰기 전에:
- 팀이 플랜을 원하나요? 그렇다면 위치는 어디인가요(기본
docs/plan.yaml)? 이미 존재하는 플랜이 있나요? 위 형식의 파일이라면 기존 파일을 그대로 사용할 수 있습니다. - 언제 다시 빌드할까요? Action은 UTC를 사용하며, 기본값은 매일 11:00 UTC입니다.
그런 다음 저장소의 최상위 폴더에서:
python SCRIPT init # 스크립트 + 일일 Action
python SCRIPT init --with-plan # ... 및 시작용 docs/plan.yaml
python SCRIPT init --plan path/to/plan.yaml # ... 기존 플랜 사용
init은 .github/dashboard/ (스크립트)와 .github/workflows/dashboard.yml을 작성하며, 기존 파일이 있으면 덮어쓰지 않습니다. 그 다음:
- 페이지를 로컬에서 한 번 빌드하고(다음 섹션) 보여줘서 작동하는지 확인합니다.
- 시작용 플랜을 작성했다면 사용자와 함께 채웁니다: 그룹, 박스, 소유자, 각 소유자 이름을 GitHub 로그인에 매핑하는
people목록. - 커밋할 내용(
init이 작성한 파일과 플랜)을 알려주고, 기본 브랜치에 도달한 후 Actions 탭에서 바로 실행할 수 있다고 알려줍니다("Dashboard", 그런 다음 "Run workflow"). - 매일 아침 확인하는 방법을 알려줍니다:
git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html, 그런 다음dashboard.html을 엽니다. 공개 저장소의 경우 대신dashboard브랜치에 대해 GitHub Pages를 활성화하고 웹 주소를 얻을 수 있습니다.
Action이 푸시 중 "Permission denied" 오류로 실패하면 저장소나 조직이 Actions의 권한을 제한하는 것입니다: Settings → Actions → General → Workflow permissions, "Read and write". 이 설정은 사용자가 직접 변경해야 합니다.
워치 리스트 설정 (여러 저장소)
한 번에 물어보세요: 어떤 저장소를 감시할지(owner/name 형식), 각 저장소의 플랜이 docs/plan.yaml 외의 다른 위치에 있는지, 워치 리스트를 보관할 사용자의 저장소(비어 있는 새 저장소도 가능), 그리고 다시 빌드할 시간(UTC).
아무것도 쓰기 전에 페이지를 한 번 빌드하여 사용자에게 보여줍니다:
python SCRIPT watch --list <scratch dir>/watchlist.yaml --out <scratch dir>/radar
해당 폴더에서 index.html을 엽니다. 읽을 수 없는 저장소는 다른 저장소를 중단시키지 않고 해당 행에 오류를 표시합니다: 일반적으로 이름 오타나 비공개 저장소입니다.
그런 다음 워치 리스트를 보관할 저장소에서:
python SCRIPT init --watch # 스크립트, watchlist.yaml, .github/workflows/radar.yml
사용자의 저장소를 watchlist.yaml에 기록한 후 알려줍니다:
- 커밋할 내용(
init --watch가 작성한 파일)과 기본 브랜치에 도달한 후 Actions 탭에서 바로 실행할 수 있다고 알려줍니다("Radar", 그런 다음 "Run workflow"). - 비공개 저장소에는 토큰이 필요합니다. Action은 공개 저장소와 자신의 저장소만 읽을 수 있고 그 외에는 읽을 수 없습니다. 비공개 저장소를 감시하려면 사용자가 해당 저장소를 읽을 수 있는 GitHub 토큰을 만들고, 감시 저장소에
RADAR_TOKEN이라는 이름의 시크릿으로 저장합니다(Settings → Secrets and variables → Actions). 사용자가 직접 수행해야 하며, 토큰을 요청하거나 붙여넣지 마세요. - 매일 아침 확인하는 방법:
mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar, 그런 다음radar/index.html을 엽니다.
나중에 저장소를 추가하거나 제거하려면 watchlist.yaml만 편집하면 되고 다른 것은 변경할 필요가 없습니다.
저장소의 스크립트 사본 업데이트
init은 스크립트를 저장소에 복사하므로, 누군가 업데이트할 때까지 저장소는 받은 버전을 계속 실행합니다. 사용자가 저장소에서 repo-radar 업데이트를 요청하거나, 이 스킬의 스크립트가 저장소의 것보다 최신인 경우, 저장소의 최상위 폴더에서 실행하세요:
python scripts/dashboard.py update # 이 스킬의 사본, .github/dashboard/의 것이 아님
.github/dashboard/의 스크립트만 교체하고 변경된 파일을 알려줍니다. Action, 워치 리스트, 플랜은 사용자가 남긴 그대로 유지됩니다. 그런 다음 .github/dashboard/를 커밋하도록 알려주세요.
지금 확인하기
python SCRIPT build --out <scratch dir>/dashboard.html
저장소 내에서 실행하거나(--repo owner/name 전달) 저장소 외부의 임시 폴더에 페이지를 작성하여 커밋되지 않도록 한 후 사용자에게 보여줍니다. "여기서 시작" 카드와 플랜 탭의 노란색 태그부터 시작하여 평이한 언어로 설명합니다. 모든 숫자는 맥락을 포함해야 합니다: "12개 필요"가 아니라 "열린 PR 16개 중 12개가 리뷰 필요"와 같이.
내 위치 (한 사람, 플랜 기준)
두 가지 이름이 필요합니다: 플랜에 적힌 소유자 이름과 GitHub 로그인. 플랜의 people 목록에 gh가 로그인한 로그인이 있으면 스크립트가 자체적으로 이름을 찾습니다. 그렇지 않으면 물어보고 --owner "<이름>"을 전달하세요. 사용자가 다른 사람에 대해 물을 때만 --login을 전달하세요.
사용자가 풀 리퀘스트 브랜치에 있을 때 두 번 실행하세요. main은 팀이 오늘 보는 것을 보여주고, 브랜치는 이 풀 리퀘스트가 변경할 것을 보여줍니다:
git fetch origin
python SCRIPT me --ref origin/main
python SCRIPT me
보고서는 네 개의 표로 구성됩니다:
| 표 | 사용자에게 알려주는 내용 |
|---|---|
| 귀하의 박스 | 소유하거나 PR이 있는 각 박스: 빌드됨, 시뮬레이션됨, PR에 있음, 누락된 항목 수 |
| 아직 누락된 항목 | 다음 작업, 박스별 |
| pr로 표시된 항목 (GitHub 확인) | 열린 PR은 아무 작업 필요 없음. 머지된 PR은 주간 리프레시 준비 완료. 닫히고 머지되지 않은 PR은 항목을 missing으로 되돌려야 함 |
| 플랜에 항목이 없는 귀하의 열린 PR | 플랜이 아직 보여주지 않는 작업 |
이 순서로 설명하세요: 완료 및 리뷰 중인 것; 플랜에서 누락된 PR과 각각이 속할 가능성이 있는 박스; 머지되지 않고 닫힌 PR의 항목; 첫 번째 누락된 항목이 다음 작업일 가능성이 높음.
플랜에 풀 리퀘스트 추가 (요청 시에만)
main이 아닌 사용자의 풀 리퀘스트 브랜치에서 작업하세요.
- 풀 리퀘스트 번호 찾기:
gh pr view --json number,title. - 해당 풀 리퀘스트가 빌드하는 항목 찾기. 플랜에서 사용자의 박스를 읽으세요.
- 항목이 이미 작업을 설명하고 있으면 상태를
pr로 변경하고pr: <번호>를 추가하세요. - 해당 항목이 없으면 올바른 박스에 추가하세요:
{status: pr, pr: <번호>, text: "<빌드하는 내용>"}.text는 짧고 평이하게 유지하세요. 명확하지 않으면 사용자에게 어떤 박스인지 물어보세요.
- 항목이 이미 작업을 설명하고 있으면 상태를
- 플랜이 여전히 로드되는지 확인:
python SCRIPT build --out <scratch dir>/check.html. 문제가 있으면 오류 메시지와 함께 중단됩니다. me를 다시 실행하세요. 이제 PR이 "플랜에 항목 없음"이 아닌 "pr로 표시된 항목" 아래에 있어야 합니다.- 사용자의 풀 리퀘스트에 플랜 파일을 커밋하세요.
주간 리프레시 (수행하는 사람만)
main에서 페이지를 빌드하거나 각 소유자에 대해 me --ref origin/main을 한 번 실행하세요. 그런 다음 하나의 풀 리퀘스트에서:
- PR이 머지된 각 항목을
built로 표시하거나, 머지된 작업이 스텁, 페이크, 스켈레톤인 경우simulated로 표시하세요. 플랜 탭에서 "머지됨" 태그가 붙습니다. - 머지되지 않고 닫힌 PR의 각 항목을
missing으로 되돌리세요. - 플랜에 항목이 없는 열린 PR(플랜 탭의 마지막 섹션)을 풀 리퀘스트 설명에 나열하여 소유자가 배치할 수 있도록 하세요. 박스를 추측하지 마세요.
as_of를 확인한 main 커밋과 날짜로 설정하세요.
네트워크 없이 사용
python SCRIPT fetch --out data.json은 GitHub의 응답을 저장합니다. 그런 다음 build --data data.json과 me --data data.json으로 오프라인에서 작업할 수 있습니다. 테스트에서 이 방식을 사용합니다.