🤝 기여 가이드

이 문서는 “음성 명령 기반 공구 서랍 관리 로봇팔 어시스턴트” 프로젝트의 Organization 공통 기여 규칙입니다.

사용자가 음성으로 특정 공구를 요청하면, 시스템은 공구를 인식하고 위치를 추정한 뒤 로봇팔과 그리퍼로 공구를 집어 사용자 앞 전달 위치 또는 사용자 손 방향으로 안전하게 전달합니다. 이후 반납된 공구를 원래 위치로 정리하는 기능도 목표에 포함합니다.

📦 레포지토리 역할

• macgyvbot-assistant: ROS 2 메인 시스템, 작업 상태 관리, 로봇팔/그리퍼/서랍 제어
• macgyvbot-perception: 공구 인식, 위치 추정, 모델 학습/추론 파이프라인
• macgyvbot-datasets: 데이터 수집, 라벨링, 메타데이터, 데이터셋 버전 관리
• macgyvbot-docs: 기획서, 요구사항 명세서, 발표자료, 다이어그램
• macgyvbot-vla: OpenVLA 기반 조작 skill 실험 및 파인튜닝
• macgyvbot-simulation: Isaac Sim, Gazebo, RViz 기반 시뮬레이션

🌿 브랜치 네이밍 규칙

작업 목적과 이슈 번호가 드러나도록 작성합니다.

feature/#12-tool-detection-node
bugfix/#18-camera-index-error
docs/#5-update-requirements
experiment/#22-yolo-training
safety/#31-limit-handover-speed

권장 prefix:

• feature/#: 신규 기능
• bugfix/#: 버그 수정
• docs/#: 문서 수정
• experiment/#: 실험 코드 또는 실험 기록
• safety/#: 안전 관련 수정
• refactor/#: 리팩토링
• task/#: 설정, 빌드, 기타 일반 작업

✍️ 커밋 메시지 규칙

커밋 메시지는 다음 형식을 권장합니다.

type: 변경 내용 요약

type 예시:

• feat: 신규 기능 추가
• fix: 버그 수정
• docs: 문서 수정
• refactor: 기능 변화 없는 구조 개선
• test: 테스트 추가 또는 수정
• task: 설정, 빌드, 기타 일반 작업
• experiment: 모델 학습, 로봇 제어, 시뮬레이션 실험
• safety: 안전 제한, 비상정지, 전달 동작 관련 수정

예시:

feat: add tool detection ROS 2 node
fix: handle camera index fallback
experiment: compare yolo tool detection models
safety: limit handover speed near user hand

🔀 PR 규칙

• PR은 가능한 한 하나의 목적만 포함합니다.
• 관련 이슈를 PR 본문에 연결합니다.
• 테스트 결과를 PR 템플릿에 기록합니다.
• 로봇 제어, 그리퍼 동작, 서랍 개폐, 사용자 손 전달 변경은 안전 관점의 리뷰를 요청합니다.
• 대용량 모델 파일, 데이터셋, 영상, ROS bag 파일은 PR에 직접 포함하지 않습니다.

📝 이슈 작성 규칙

• 버그는 재현 방법, 실행 환경, 로그를 포함합니다.
• 기능 제안은 필요한 이유와 완료 조건을 포함합니다.
• 실험 이슈는 실험 환경, 방법, 평가 지표, 결과 표를 포함합니다.
• 안전 이슈는 일반 버그보다 우선 검토합니다.

🧹 코드 스타일 기본 원칙

• 이름은 역할이 드러나게 작성합니다.
• 설정값은 코드에 하드코딩하지 않고 설정 파일로 분리합니다.
• 로그 메시지는 문제 원인을 추적할 수 있게 작성합니다.
• 실패 상황을 무시하지 말고 명시적으로 처리합니다.
• 불필요한 리팩토링과 포맷 변경은 별도 PR로 분리합니다.

🤖 ROS 2 개발 규칙

• 노드 이름은 역할이 명확하게 드러나도록 작성합니다.
• topic, service, action 이름과 메시지 타입을 문서화합니다.
• 새 노드나 파라미터를 추가하면 launch 파일을 함께 업데이트합니다.
• 설정값은 YAML 파일로 분리합니다.
• 실제 로봇 실행 전에 dry-run 또는 시뮬레이션 실행을 권장합니다.
• 로봇팔 이동, 그리퍼 파지, 서랍 개폐, 사용자 전달 동작은 실패 복구 경로를 고려합니다.

🧠 모델/데이터 관리 규칙

다음 파일은 Git에 직접 올리지 않습니다.

• .pt
• .onnx
• .engine
• .bag
• .db3
• 대용량 이미지/영상 파일
• 대용량 학습 데이터셋

필요한 경우 다음 방식을 사용합니다.

• Google Drive
• Hugging Face Dataset
• Git LFS
• 별도 모델 registry 또는 artifact storage

데이터셋 변경 시 라벨 기준, 수집 환경, 카메라 각도, 조명 조건, 버전 정보를 함께 기록합니다.

🚨 안전 규칙

• 로봇 작업 공간 제한을 설정합니다.
• 로봇팔과 그리퍼 속도 제한을 적용합니다.
• 비상정지 동작을 실제 실행 전에 확인합니다.
• 사용자 손과 로봇팔/공구 사이의 최소 거리를 유지합니다.
• 사용자 손 방향 전달 기능은 낮은 속도와 제한된 작업 공간에서 먼저 검증합니다.
• 실제 로봇 실행 전 dry-run 또는 시뮬레이션을 권장합니다.
• 안전 관련 변경은 safety 라벨을 사용하고 우선 리뷰를 요청합니다.

👀 리뷰 우선순위

위험도 기반으로 다음 순서를 우선합니다.

1. safety: 사용자, 로봇팔, 그리퍼, 공구, 서랍/트레이 관련 안전성
2. robot-control: 로봇팔 이동, 그리퍼 파지, 서랍 개폐, 전달 동작
3. perception: 공구 인식, 위치 추정, 모델 추론
4. docs: 문서, 발표자료, 다이어그램, 가이드