콘텐츠로 이동

도입 지표와 성장 성과표

SchemaRouter는 별(star) 개수만이 아니라 검증 가능한 사용과 실제 도입을 성장 지표로 측정합니다. 마케팅 분석만을 위해 사생활을 침해하는 제품 텔레메트리를 추가하지 않습니다.

기준선

캠페인 전 GitHub 지표의 기준선은 2026-10-01에 수집했습니다.

지표 기준선
GitHub stars 1
Forks 0
Subscribers 1
Network count 0
Open issues + PRs 26

자동화된 성과표는 PyPIStats에서 패키지 다운로드 수를 조회하고, GitHub의 최근 14일 트래픽 API도 시도합니다. 이 값들은 시간 구간에 따라 달라지는 외부 데이터이므로, 임의의 수치를 저장소에 적는 대신 최초로 성공한 성과표 실행을 정본 PyPI·트래픽 기준선으로 사용합니다.

자동 수집

Growth Scorecard GitHub Actions 워크플로는 매주 월요일에 실행되며 수동으로 실행할 수도 있습니다.

수집하는 항목:

  • GitHub stars, forks, subscribers, 열린 이슈와 PR, network count, topics, 저장소 관련 날짜
  • 직전 하루·일주일·한 달의 PyPI 다운로드
  • 토큰에 충분한 권한이 있을 경우 최근 14일 동안의 GitHub 조회수와 클론 수
  • 수집 시각과 각 지표의 명시적인 한계

매번 실행할 때 90일 동안 보존하는 JSON 및 Markdown 아티팩트를 작성하고, Markdown 요약을 워크플로 화면에도 표시합니다.

수집기는 다음 명령으로 실행합니다.

python scripts/capture_growth_scorecard.py \
  --json-out /tmp/growth-scorecard.json \
  --markdown-out /tmp/growth-scorecard.md

권한 모델

공개 GitHub 저장소 메타데이터와 PyPIStats에는 비공개 텔레메트리가 필요하지 않습니다. 반면 저장소 트래픽은 별도의 API이며 GitHub에서 트래픽 조회 권한이 있는 사용자와 토큰만 접근할 수 있습니다.

따라서 워크플로는 트래픽을 선택적 증거로 처리합니다. 기본 GITHUB_TOKEN으로 접근할 수 없는 경우 전체 수집을 실패시키지 않고 아티팩트에 unavailable이라고 표시합니다.

유지보수 담당자는 필요한 최소 트래픽 읽기 권한만 부여한 SCHEMAROUTER_GROWTH_GITHUB_TOKEN 시크릿을 선택적으로 구성할 수 있습니다. 쓰기 권한은 필요하지 않습니다.

선행 지표와 후행 지표

선행 지표

  • 일간·주간·월간 PyPI 다운로드
  • 조회 가능한 경우 저장소 조회수와 순 방문자 수
  • 조회 가능한 경우 저장소 클론 수와 순 클론 사용자 수
  • 이슈로 드러난 Quickstart 및 예제 실행 실패
  • 다른 프로젝트가 공개한 통합 기능이나 패키지 extra 사용 근거

후행 지표

  • Stars
  • Forks
  • Subscribers
  • 외부 기여자
  • 검증 가능한 외부 도입 프로젝트와 사례 연구

실제 설치·도입 근거 없이 별 개수만 증가했다면 제품 도입 성과로 보고하지 않습니다.

근거 중심의 수동 조사 지표

일부 유용한 신호는 신뢰할 만하고 개인정보를 보호하는 공개 API가 없습니다.

  • SchemaRouter를 의존성으로 사용하거나 참조하는 외부 저장소
  • 하위 프로젝트에서의 CI 사용
  • 설치부터 첫 성공까지의 시간
  • 프레임워크·플러그인 연동 기능의 도입
  • 사례 연구와 독립적 재현 검증

이러한 항목은 확인 가능한 공개 근거가 있을 때만 추가합니다. GitHub 검색의 잡음으로부터 추정하거나 트래픽 숫자를 근거 없이 가공하지 않습니다.

스냅샷 수집 주기

  • 매주: 자동화된 워크플로 스냅샷을 생성합니다.
  • 매월: 대표적인 워크플로 아티팩트 하나를 보존하고 의미 있는 변화를 #583에 요약합니다.
  • 캠페인 전후: 비교에 사용한 정확한 실행 ID를 기록합니다.
  • 릴리스별: 데이터 소스가 뒷받침할 때에만 버전별 다운로드를 비교합니다.

해석 시 유의사항

PyPI 다운로드에는 CI 설치 및 반복 설치가 포함되므로 고유 사용자 수가 아닙니다. GitHub 트래픽은 이동하는 최근 14일 창으로 집계됩니다. Stars는 사용량보다 인지도를 반영하는 경향이 있습니다. 열린 이슈 수에는 버그 신고뿐 아니라 연구 트래커와 예정된 작업도 함께 포함됩니다.

따라서 성장에 관한 결정에는 여러 신호를 종합하고, 외부 도입 근거를 단순 집계 수치와 분리해서 관리해야 합니다.