Weblate 모듈에 기여하기¶
주요 저장소 외에도 Weblate는 여러 Python 모듈로 구성됩니다. 이 모듈들은 모두 동일한 구조를 따르며 이 문서에서 모두 다룹니다.
예를 들어 다음을 포함함:
wlc, Python 클라이언트 라이브러리 ( Weblate 클라이언트 참조)
translation-finder, 저장소에서 번역 가능한 파일을 검색하는 데 사용
language-data, Weblate용 언어 정의 ( 언어 정의 참조)
translate-toolkit, 번역 파일을 조작하는 라이브러리. 원래 타사 라이브러리였으나 현재 Weblate에서 유지보수합니다.
내장 언어 정의 확장하기¶
언어 정의는 language-data 저장소에 있습니다.
languages.csv 에 누락된 언어 정의를 자유롭게 추가할 수 있습니다. 다른 파일은 해당 파일에서 생성됩니다. CSV 파일의 열은 언어 정의 에 대응합니다.
라이선스 및 저작권¶
프로젝트 코드에 기여할 때는 달리 명시하고 합의하지 않는 한 변경사항과 새 코드를 저장소 라이선스인 GPL-3.0-or-later 아래에 두는 데 동의하는 것입니다. 새 소스 파일은 기존 저작권 및 SPDX 라이선스 헤더 스타일을 따라야 합니다.
더 허용적인 라이선스를 사용하는 저장소와 공유되는 파일처럼 의도적인 이유가 있을 때만 다른 라이선스를 사용하세요.
더 보기
Weblate 라이선스 에서 라이선스에 대해 더 자세히 설명합니다.
좋은 패치 작성하기¶
개별 변경 사항 작성¶
11개의 문제를 수정한다고 하는 대규모 패치를 받았지만 토론과 의견에서 10개에 동의하지 않거나 9개가 이미 다른 방식으로 수정된 경우는 성가신 일입니다. 이 경우 이 변경 사항을 병합하는 사람은 방대한 소스 더미에서 관심 있는 단일 패치를 추출해야 하며 이는 많은 추가 작업을 발생시킵니다.
가급적 각 문제를 해결하는 수정 사항은 정확히 무엇을 수정하는지 설명하는 자체 설명/커밋 메시지가 포함된 개별 패치/커밋에 있어야 합니다. 이렇게 하면 유지 관리자나 기타 관심 당사자가 모든 변경 사항을 선택적으로 적용할 수 있습니다.
또한 개별 변경 사항은 향후 문제 및 회귀를 추적하기 위한 이진 탐색을 훨씬 더 용이하게 합니다.
문서¶
문서화는 지루한 작업일 수 있지만 누군가가 완료해야 합니다. 코드 변경과 함께 문서를 제출하면 일이 훨씬 쉬워집니다. 메서드, 복잡한 코드 블록 또는 사용자에게 보이는 기능을 문서화하는 것을 잊지 마세요.
더 보기
테스트 케이스¶
테스트를 통해 기능이 예상대로 작동하는지 빠르게 확인할 수 있습니다. 이 상황을 유지하고 개선하기 위해 추가된 모든 새 기능과 함수는 테스트 모음에서 테스트해야 합니다. 추가된 모든 기능에는 문서화된 대로 작동하는지 확인하는 최소 하나의 유효한 테스트 케이스가 있어야 합니다.
커밋 메시지¶
Git 커밋은 Conventional Commits 명세를 따라야 합니다.
타입 검사¶
모든 새 코드는 PEP 484 타입 힌트를 사용해야 합니다. Django 앱의 타입 검사를 실용적으로 만드는 Django 플러그인이 있으므로 mypy 로 이를 검사합니다.
새 코드와 변경된 코드는 현재 Django 타이핑 지원으로 실용적인 범위에서 새로운 mypy 실패를 만들면 안 됩니다. 코드베이스는 아직 타입 주석으로 완전히 덮여 있지 않고, 일부 Django 구성은 정확하게 주석 달기 어렵습니다. 따라서 CI는 선택한 모듈에 대해서만 mypy 를 강제하고, 다른 발견 사항은 별도로 보고합니다.
코딩 표준 및 코드 린팅¶
코드는 PEP 8 코딩 가이드라인을 따르고 ruff 코드 포맷터를 사용하여 포맷팅해야 합니다.
코드 품질을 확인하려면 ruff 를 사용할 수 있으며 구성은 pyproject.toml 에 저장됩니다.
When suppressing a ruff diagnostic, prefer
# ruff: ignore[rule-name] with the human-readable rule name. Place the
comment on the line above the logical statement or block when that does not
broaden the suppression scope. Keep the comment inline when moving it would
change the scope, affect import sorting, or get between another tool’s
disable-next comment and the code it targets.
이 모든 것을 적용하는 가장 쉬운 방법은 prek 을 설치하는 것입니다. 이것은 Weblate에서 사용하는 pre-commit 도구의 타사 재구현입니다. pyproject.toml 에 선언된 개발 의존성에 포함되어 있으므로 해당 의존성을 설치하면 prek 을 사용할 수 있습니다.
모든 파일을 수동으로 확인하려면 실행:
uv run prek run --all-files
원본 pre-commit 클라이언트를 선호하는 경우 .pre-commit-config.yaml 의 동일한 구성을 사용합니다.
보안을 고려한 코딩¶
Weblate의 모든 코드는 Security by Design Principles 을 염두에 두고 작성해야 합니다.
AI 가이드라인¶
프로젝트에 콘텐츠를 기여할 때 이를 있는 그대로 사용할 수 있는 권한을 부여하며, 우리에게 배포할 수 있는 권한이 있는지 확인해야 합니다. 변경 사항을 제출하면 해당 변경 사항이 프로젝트에 채택되어 프로젝트 라이선스에 따라 재배포될 수 있고 해야 한다는 것에 동의합니다. 작성자는 라이선스가 없는 코드가 프로젝트에 제출되지 않도록 할 책임이 있음을 명확히 인식해야 합니다.
이는 AI를 사용하는지 여부와 무관합니다.
풀 리퀘스트를 기여할 때 당연히 항상 제안이 양호한 품질이고 가이드라인을 따르는 최선의 노력인지 확인해야 합니다. 기본적인 경험 법칙은 누군가가 기여가 AI의 도움으로 이루어졌다는 것을 알아챌 수 있다면 아직 할 일이 더 있다는 것입니다.
AI의 도움으로 작성된 코드도 프로젝트에 수용할 수 있지만 코드는 여전히 코딩 표준을 따르고, 명확하게 작성되고, 문서화되고, 테스트 케이스가 있으며, 일반적인 모든 요구 사항을 준수해야 합니다.