코드 라이브러리 개발 가이드#
코드 규범#
좋은 코드를 작성하는 것은 단순히 무엇을 썼는지뿐만 아니라, 어떻게 작성했는지에도 달려 있습니다. 지속적 통합 테스트 중에는 여러 도구가 코드의 스타일 오류를 검사합니다. 좋은 프로그래밍 스타일은 Xinference에 코드를 제출하기 위한 요구 사항 중 하나입니다.
또한, 코드에 갑작스러운 변경을 가하지 마십시오. 이는 많은 사용자 코드에 문제를 일으킬 수 있습니다. 따라서 대규모 장애를 방지하기 위해 가능한 한 하위 호환성을 유지해야 합니다.
자동 수정 포맷 오류#
또한, 지속적 통합(CI)은 pre-commit hooks 을 사용하여 black, flake8, isort 등과 같은 코드 포맷 검사 도구를 실행합니다. 이러한 검사에서 생성된 모든 경고는 지속적 통합을 실패하게 만듭니다. 따라서, 코드를 커밋하기 전에 이러한 검사를 직접 실행하는 것이 좋습니다. Xinference 저장소의 루트 디렉터리에서 ``pre-commit``을 설치하여 이를 수행할 수 있습니다:
pip install pre-commit
그런 다음 명령을 실행하십시오:
pre-commit install
설치가 완료되면 매번 변경 사항을 커밋할 때 모든 스타일 검사가 자동으로 실행되어 수동으로 하나씩 실행할 필요가 없습니다. 또한 ``pre-commit``을 사용하면 코드 검사가 변경될 때 쉽게 동기화 상태를 유지할 수 있습니다.
참고로, 필요 시 git commit --no-verify 명령어를 사용하여 이러한 검사를 건너뛸 수 있습니다.
``pre-commit``를 워크플로의 일부로 포함하지 않으려면, 다음 명령을 실행하여 검사를 수행할 수 있습니다:
pre-commit run --files <files you have modified>
사전에 ``pre-commit install``을 실행할 필요가 없습니다.
모든 최근에 제출된 파일에 대해 검사를 실행하려면 다음 명령을 사용할 수 있습니다:
pre-commit run --from-ref=upstream/main --to-ref=HEAD --all-files
사전에 ``pre-commit install``을 실행할 필요가 없습니다.
참고
정기적으로 pre-commit gc 명령을 실행하여 더 이상 사용되지 않는 저장소를 정리하는 것을 고려할 수 있습니다.
하위 호환성#
가능한 한 하위 호환성을 유지하세요. 변경이 반드시 필요하다고 판단되면, 풀 리퀘스트에서 그 이유를 명확히 설명하세요. 또한, 메서드 시그니처를 변경할 때는 주의하고, 필요 시 폐기 경고를 추가하세요. 아울러, 폐기된 함수나 메서드에는 sphinx 지시어를 추가하세요.
또한 당신은 ~해야 합니다.
새로운 테스트 샘플을 작성하여, 더 이상 사용되지 않는 매개변수를 호출할 때 경고가 발생하도록 합니다.
모든 Xinference 기존 테스트 샘플과 코드를 새로운 파라미터를 사용하도록 업데이트하십시오.
Type Hint#
Xinference는 PEP 484 스타일의 타입 힌트 사용을 강력히 권장합니다. 새로운 개발에는 타입 힌트를 포함해야 하며, 기존 코드에 주석을 추가하는 풀 리퀘스트도 환영합니다!
테스트 주도 개발#
Xinference는 테스트를 매우 중요하게 여기며, 기여자들이 테스트 주도 개발(TDD) 을 채택할 것을 적극 권장합니다. 이 개발 프로세스는 “매우 짧은 개발 주기의 반복에 의존합니다: 먼저, 개발자는 필요한 개선 사항이나 새로운 기능을 정의하는 (초기에는 실패하는) 자동화된 테스트 샘플을 작성하고, 그런 다음 최소한의 코드로 해당 테스트를 통과시킵니다.” 따라서 실제로 코드를 작성하기 전에 테스트 샘플을 먼저 작성해야 합니다. 일반적으로 테스트 샘플은 원래의 GitHub 이슈에서 얻을 수 있습니다. 그러나 추가적인 경우를 고려하고 그에 맞는 테스트 샘플을 작성하는 것도 가치가 있습니다.
코드를 Xinference에 푸시한 후에는 테스트 샘플을 추가하라는 요청을 자주 받게 됩니다. 따라서 미리 테스트 샘플을 작성하는 습관을 들이는 것이 문제를 예방하는 데 매우 중요합니다.