Contributing Docs

문서 작성 가이드

이 Wiki는 설치·차종 사례와 문서 탐색을 담당합니다. 설정과 코드 동작의 상세 설명은 carrot-wip의 docs/user/ko와 docs/user/en에서 코드와 함께 관리하며, Wiki에는 같은 내용을 다시 복사하지 않습니다.

기준 자료

설명은 가능하면 다음 순서로 확인합니다.

1. carrot-wip의 현재 실행 코드
2. openpilot/selfdrive/carrot_settings.json의 메뉴, 범위, 단위와 설명
3. UI의 한국어 번역과 실제 화면
4. 테스트와 브랜치별 분석 문서
5. 기존 GitBook 문서는 역사적 참고 자료로만 사용

기존 문서와 코드가 다르면 코드를 기준으로 하되, 코드 자체가 잘못된 것으로 보이면 문서를 억지로 맞추지 말고 이슈로 분리합니다.

한 페이지의 권장 형식

1. 이 페이지가 해결하는 문제
2. 적용 대상과 적용되지 않는 대상
3. 안전 또는 데이터 손실 경고
4. 사용자가 따라 할 순서
5. 성공 여부를 확인하는 방법
6. 원상 복구 방법
7. 관련 페이지

차량별 문서는 제목과 첫 부분에 차종, 연식, 트림, CAN 구성과 검증 날짜를 적습니다.

설정 문서 작성 규칙

• 화면 제목과 내부 파라미터 이름을 함께 씁니다.
• x0.01, cm, % 등의 단위를 생략하지 않습니다.
• 최소값, 최대값, 기본값을 수동으로 복사할 때는 carrot_settings.json과 Params 등록값이 일치하는지 함께 확인합니다.
• 차량별 결과를 전체 차량의 권장값으로 일반화하지 않습니다.
• “값을 높이면 무엇이 바뀌는가”와 “잘못 조정했을 때 증상”을 함께 적습니다.
• 변경 전 백업과 원상 복구 단계를 포함합니다.

코드 변경과 함께 확인할 문서

사용자에게 보이는 설정, 기본값, 단위, 프리셋, 차량 제어, 레이더 또는 Carrot Web 설정 화면을 바꾸면 docs/user/docs_map.json에서 연결된 한국어·영어 문서 쌍과 집중 테스트를 같은 코드 변경에서 갱신합니다. 어느 한 언어만 바꾸면 자동 검사가 실패합니다.

python tools/docs/check_user_docs.py --base origin/carrot-wip

동작이 바뀌지 않는 리팩터링·로그·성능·테스트 전용 변경은 Pull Request 본문에 Docs-Not-Needed: 구체적인 이유를 남깁니다. 공개 Wiki와 docs/user에는 사용자에게 제공할 수 있는 기능만 설명하고, 내부 개발 자료나 비공개 기능의 이름·주소·사용법은 옮기지 않습니다.

앞으로 추가로 자동화할 부분

코드와 문서의 연결 여부는 현재 자동 검사합니다. 다음 단계로 전체 설정 사전은 165개 항목을 손으로 복사하지 않고 carrot_settings.json에서 생성하는 방식을 권장합니다. 생성기는 다음을 검사해야 합니다.

• 문서에 없는 새 파라미터
• JSON과 Params 등록값의 기본값 불일치
• 단위 또는 번역이 비어 있는 항목
• 메뉴에는 있으나 등록되지 않은 파라미터

이렇게 하면 설정이 추가될 때 설명서가 조용히 오래된 상태로 남는 문제를 줄일 수 있습니다.