Skip to content

issues.md

Latest commit

 

History

History
135 lines (108 loc) · 9.41 KB

issues.md

File metadata and controls

135 lines (108 loc) · 9.41 KB
Raw

이슈 관리 규칙

사람과 에이전트 모두 할 일·조사·계획을 GitHub 이슈(fotoner/DJCrate)로 관리한다. docs/plans/ 같은 계획 문서는 새로 만들지 않는다.

범위 — 어떤 이슈를 받나

라이브러리 관리 도구인 DJCrate의 목표는 rekordbox Export 모드의 라이브러리 관리 기능에 1:1로 대응해 더 낫게 만드는 것이다. 대상 기능은 컬렉션과 태그, 큐와 그리드, 재생 목록과 USB 내보내기다.

  • 받는 이슈는 라이브러리 정리, rekordbox에 안전하게 쓰기, USB 내보내기·가져오기다. 분석과 다른 DJ 소프트웨어·AI 도구와의 연동도 받는다.
  • Performance 모드의 두 덱 믹싱·이펙트와 녹음·컨트롤러 연결 같은 랩탑 공연 이슈는 받지 않는다. 이런 이슈는 "not planned"로 닫는다.
  • 덱은 큐·그리드를 고칠 때 미리 듣는 용도로만 쓴다.
  • 한 사람의 쓰임새에만 맞는 규칙은 설정으로 켜는 선택 기능으로 둔다(예: 코멘트 형식). 이런 규칙은 기본으로 켜 두지 않는다.

제목

제목은 마침표 없는 한국어 한 줄로 쓴다. 종류는 라벨로 나타내므로 [기능] 같은 머리말을 붙이지 않는다.

종류 제목에 쓸 것 예
기능·정리·조사 할 일을 "하기"로 쓴다. " 정리", "~ 확인"처럼 명사로 끝나도 된다 태그를 rekordbox에 직접 쓰기
버그 무엇이 어떻게 잘못되는지 쓴다 rekordbox에서 곡을 지우고 돌아와도 목록이 그대로임
상위 이슈 주제 이름 USB 내보내기·가져오기

라벨

이슈마다 종류 1개 + 영역 1개 이상 + 우선순위 1개를 붙인다. 막힌 이유가 있으면 needs: 라벨을 더한다.

묶음 라벨 뜻
종류 feature 새 기능·기능 개선
bug 잘못 동작함
research 결과가 지식인 일(형식 분석·규칙 확인). 결론은 댓글과 문서로 남긴다
chore 정리·리팩터링·빌드·도구
perf 동작을 유지하는 성능 측정·개선
docs 문서
epic 상위 이슈. 하위 이슈를 묶기만 하고 직접 작업하지 않는다
영역 area:rekordbox rekordbox DB·분석 파일 읽기·쓰기(RekordboxKit)
area:usb USB 내보내기·가져오기·복구
area:app 앱 화면·사용 흐름
area:analysis 파형·그리드·조성·음량 분석(DJCAnalysis)
area:cli djc 명령
area:ai AI 에이전트 연동(MCP·스킬)
area:virtualdj VirtualDJ 연동
area:ci 빌드·테스트·배포 자동화, 저장소 운영(기여 안내·라이선스)
우선순위 P0 rekordbox 라이브러리나 USB를 깨뜨릴 수 있음. 하던 일을 멈추고 먼저
P1 다음에 할 것
P2 할 것, 순서는 미정
P3 아이디어. 할지 아직 정하지 않음
막힘 needs:experiment 사용자가 직접 해 보는 실험(rekordbox·VirtualDJ에서 편집 등)이 있어야 진행됨
needs:device CDJ·XDJ 실기기 확인이 있어야 진행됨
needs:decision 사용자가 정할 것이 남음(무엇을 정해야 하는지 본문이나 댓글에 적는다)
기타 design Apple HIG·화면 설계(area:app과 함께)
good first issue 처음 기여하는 사람에게 알맞음
  • 다른 이슈가 먼저 끝나야 하면 라벨 대신 GitHub의 "blocked by" 관계를 건다(gh issue edit N --add-blocked-by M).
  • 영역 라벨은 같은 영역 이슈가 3개 이상 모일 때 만든다. 새 라벨은 이 표에 먼저 더한다.
  • 중복 이슈나 안 하기로 한 이슈는 라벨 대신 닫는 이유(duplicate, not planned)로 나타낸다.

본문

본문은 템플릿(.github/ISSUE_TEMPLATE/)의 섹션 가운데 필요한 것만 남겨 쓴다.

종류 섹션
기능·정리·문서 ## 배경(왜) · ## 목표(끝나면 무엇이 되나 = 닫는 기준) · ## 할 일 · ## 참고
버그 ## 증상 · ## 재현 · ## 기대 · ## 환경(DJCrate 커밋, rekordbox 버전, macOS)
조사 ## 질문 · ## 방법 · ## 결론(끝나면 채운다)
상위 ## 목표 · ## 순서 · ## 범위 밖
  • 상위 이슈의 하위 이슈 목록과 진행률은 GitHub 하위 이슈 기능이 보여 주므로 본문에 체크리스트로 옮겨 적지 않는다.
  • 상위 이슈의 ## 순서에는 작업 순서만 번호 목록으로 적는다.
  • ## 할 일 체크리스트에는 한 브랜치로 끝낼 크기의 일을 한 줄씩 적는다. 따로 브랜치·실험·결정이 필요한 일은 하위 이슈로 뺀다.
  • rekordbox 실험으로 확인한 규칙에는 ## 확인한 규칙 (rekordbox 7.2.18 실험)처럼 버전을 적는다.
  • 규칙을 확정하면 docs/rekordbox-internals.md로 옮긴 뒤 이슈에는 링크만 남긴다.

조사 댓글

  • 조사 결과는 ## 조사 N — 주제 (YYYY-MM-DD) 제목의 댓글로 쌓는다.
  • 댓글에는 결론을 먼저 쓴다.
  • 주장마다 아래 근거 수준과 근거 링크를 붙인다.
근거 수준 뜻
[확인] 공식 자료, 여러 출처 일치, 직접 검증
[제3자] 한 프로젝트나 한 사람의 경험
[추정] 추론

공개 저장소 — 이슈에 넣지 않는 것

이 저장소는 공개 저장소이므로 아래 것은 이슈에 넣지 않는다.

  • rekordbox DB 사본·스냅샷·백업과 그 내용
  • 클라우드 토큰, agentRegistry 인증값, 자격 증명 파일
  • 개인 라이브러리 정보인 곡 수와 폴더 경로
  • 사용자 이름과 기기 일련번호
  • 대화에서 들은 내용의 출처가 된 사람의 이름이나 신상: 내용만 옮겨 근거 수준을 [제3자]로 적는다.
  • 음원 파일: 실험 곡은 골든 테스트와 같게 제목만 적는다.

흐름

  1. 만들기: 템플릿 섹션을 채운 뒤 종류·영역·우선순위 라벨을 붙인다. 큰 주제의 일부면 상위 이슈 아래에 둔다(--parent N).
  2. 고르기: P0 → P1 → P2 순으로 고른다. 막히지 않은 이슈 가운데 needs: 라벨이 없는 것은 에이전트 혼자 진행할 수 있다.
  3. 작업: dev에서 타입/<번호>-<짧은-이름> 브랜치를 딴다(예: feat/38-playlist-write). 커밋 본문에 Refs #N을, 이슈를 끝내는 커밋에는 Closes #N을 적는다. 작업 중 알게 된 것은 이슈 댓글로 남긴다.
    • 앱 UI가 바뀌는 수정은 실제 앱의 변경 전·후 화면을 캡처한다. 두 캡처는 같은 합성 데이터·재현 조건으로 찍는다.
    • UI가 바뀌지 않는 수정은 실행 명령·검증 수치·실패→통과 결과를 텍스트로 남긴다.
    • 시험 로그를 HTML·슬라이드·이미지로 만들지 않는다.
    • 캡처에 실제 라이브러리·개인 경로·인증값이 보이지 않는지 확인한다.
  4. 막힘: 맞는 needs: 라벨을 붙인 뒤 무엇이 필요한지 댓글로 적는다. 실험이면 어떤 곡에 어떤 편집을 해 달라는지까지 적는다. 부탁하는 틀은 .claude/skills/rekordbox-experiment/SKILL.md에 있다. 막힘이 풀리면 라벨을 뗀다.
  5. 닫기: 이슈는 main 릴리스가 아니라 dev에 합칠 때 닫는다. 닫는 댓글에는 합친 커밋과 확인한 것을 적는다.
    • 확인한 것은 실행한 명령과 결과 수치다. 작업 끝·합치기 직전 scripts/check.sh --changed, 필요하면 앱 자가 테스트의 결과를 적는다. 전체 검사는 릴리스 때 돈다.
    • 안 하기로 했으면 이유를 적은 뒤 "not planned"로 닫는다.
    • 앱 UI가 바뀐 이슈의 결과 댓글에는 실제 앱의 변경 전·후 스크린샷과 재현 조건, 달라진 점을 첨부한다.
    • 필요한 앱 화면이 빠졌으면 남은 작업으로 표시한다. 그 화면을 보완한 뒤에 이슈를 닫는다.
    • UI가 바뀌지 않은 이슈는 이미지 없이 검증 결과를 텍스트로 남긴 뒤 닫는다.
  6. 마일스톤: 릴리스 버전을 정하면 마일스톤을 만든다(예: v0.2.0). 그 릴리스에 넣을 이슈를 마일스톤으로 묶는다.

자주 쓰는 명령

gh issue list -l P1                                  # 다음에 할 것
gh issue list -l needs:experiment                    # 사용자 실험을 기다리는 것
gh issue list --search 'is:open -is:blocked -label:epic -label:needs:experiment -label:needs:device -label:needs:decision'
                                                     # 에이전트 혼자 진행할 수 있는 것
gh issue create -T 기능 --parent 3 -l feature,area:usb,P2   # 템플릿으로 하위 이슈 만들기(#3 USB 아래)
gh issue edit 39 --add-blocked-by 38                 # #38이 끝나야 #39를 할 수 있음
gh issue close 16 -c "dev에 합침: <커밋>. 확인: <실행한 명령과 결과 수치>"

더 보기