본문으로 건너뛰기

코딩 표준

이 가이드에서는 SiMa.ai Neat 라이브러리에 포함될 코드에 대한 기여 규칙을 정의합니다.

언어 및 API 제약 조건​

  • C++20을 사용합니다.
  • 공개 API 변경 사항은 의도적이고 최소화해야 합니다(include/*는 안정적인 것으로 간주).
  • 호환성이 유지되는 확장 기능을 사용하여 기존 기능과의 호환성을 유지하고, 호환성이 깨지는 변경 사항은 피합니다.
  • 내부 구현 세부 사항은 설치된/공개 헤더에서 제외합니다.

형식 및 스타일 규칙​

  • C/C++ 형식은 clang-format을 사용하여 적용합니다(.clang-format은 저장소 루트에 있음).
  • CMake 스타일은 scripts/check_cmake_style.py를 사용하여 적용합니다.
  • C/C++ 소스 코드에서 중복된 include는 허용되지 않습니다.
  • .editorconfig는 기본 공백 규칙(LF, 마지막 줄 바꿈, 후행 공백 없음)을 정의합니다.

푸시하기 전에 실행하십시오.

bash scripts/check_format.sh --changed-only
bash scripts/check_cmake_format.sh --changed-only
bash scripts/check_duplicate_includes.sh --changed-only

API 호환성 정책​

include/* 아래에 설치된 모든 헤더에 대해 공개 API 호환성은 필수 요구 사항입니다.

  • 호환성을 해치지 않는 추가 사항이 바람직합니다(새로운 오버로드, 새로운 선택적 필드, 새로운 API).
  • 호환성을 해치는 서명 변경(이름 변경/제거/유형 변경/매개변수 순서 변경/행동 계약 위반)은 병합 전에 검토 과정을 거쳐야 합니다.
  • 호환성을 해치는 변경이 불가피한 경우, 제거하기 전에 먼저 사용 중단 기간을 두는 것이 좋습니다(기존 서명 유지 + 대체 경로 추가).

호환성을 해치는 API 서명에 대한 필수 프로세스​

호환성을 해치는 API 변경을 병합하기 전에:

  1. PR 설명의 전용 Breaking API Change 섹션에 변경 사항을 문서화합니다.
  2. 영향 분석을 포함합니다. 영향을 받는 헤더/심볼, 예상되는 다운스트림 호환성 문제 및 마이그레이션 단계를 포함합니다.
  3. 버전 관리/릴리스 의도를 포함합니다(변경 사항이 적용될 시점).
  4. 동일한 변경 세트에서 새 API로 문서 및 예제를 업데이트합니다.
  5. 호환성을 해치는 API 표면에 대해 명시적인 유지 관리자의 승인을 받습니다.

모듈 경계​

종속성 규칙을 엄격하게 유지합니다.

  • builder/는 GStreamer 또는 pipeline/에 종속되어서는 안 됩니다.
  • gst/는 pipeline/에 종속되어서는 안 됩니다.
  • nodes/는 pipeline/에 종속되어서는 안 됩니다.
  • pipeline/은 오케스트레이터이며 gst/, builder/, nodes/, contracts/, policy/ 및 모델 내부 구성 요소에 종속될 수 있습니다.

결정성 요구 사항​

  • 노드 출력은 동일한 입력/구성에서 결정적이어야 합니다.
  • 요소 이름을 안정적이고 재현 가능하게 유지합니다.
  • 가능한 경우 결정적인 파이프라인 문자열 생성을 유지합니다.
  • 명명 동작을 변경할 때 진단 및 검증이 여전히 요소를 노드 소유권에 매핑하는지 확인합니다.

오류 처리 및 진단​

  • 실행 가능한 컨텍스트가 포함된 구조화된 오류를 선호합니다.
  • 새 오류 경로에는 PipelineReport 진단에 충분한 세부 정보가 포함되어 있는지 확인합니다.
  • 플러그인/캡/런타임 오류를 숨기는 자동 대체 기능을 피합니다.
  • 진단을 스레드 안전하게 유지합니다. 프로브 측 업데이트는 원자 또는 동등한 잠금 없는 기본 요소를 사용해야 합니다.

동시성 및 수명 주기​

  • 정리 경로에서 무한정 차단하지 않도록 합니다.
  • 런타임 상태 전환을 방어적으로 처리합니다(EOS, NULL, 타임아웃 안전 정리 경로).
  • 스트리밍 스레드 로직을 가볍게 유지하고 부작용을 제어합니다.

문서화 의무​

동작이 변경될 때:

  • 아키텍처를 업데이트합니다.
  • 워크플로 또는 조정 가능한 매개변수가 변경된 경우 사용자 가이드를 업데이트합니다.
  • 참조 문서에서 새 환경 변수를 문서화합니다.

PR 품질 기준​

기여는 다음을 포함할 때 준비된 것으로 간주됩니다.

  • 코드 및 커밋/PR 메시지에 명확한 근거를 제시합니다.
  • 새 동작 및 회귀에 대한 테스트를 포함합니다.
  • 사용자에게 보이는 모든 변경 사항에 대한 업데이트된 문서를 포함합니다.
  • 공개 헤더 변경에 대한 API 호환성 평가(해당하는 경우 전체 호환성 해치는 변경 프로세스 포함).