콘텐츠로 이동

새로운 기능 구현

제안 절차이 완료되면, 새로운 기능에 대한 완성된 설계가 마련될 것입니다. 이제 코딩을 시작할 때입니다!

특정 기능이 플랫폼별 구현을 필요로 하는 경우, 제안 과정에서 해당 아이디어가 모든 플랫폼에서 구현 가능하다는 점이 검증되었어야 합니다. 그러나 신규 기능을 최초로 구현하는 담당자로서, 모든 플랫폼에 대한 기능 구현을 책임질 필요는 없습니다. 최소한 하나의 플랫폼에 대한 완전한 구현(테스트 포함)을 제공해야 합니다. 다른 플랫폼의 경우 "스텁(stub)" 구현을 제공해야 합니다. 즉, 최소한의 인터페이스 정의만 제공하는 구현체로, 해당 플랫폼에서 동작이 구현되지 않았음을 나타내는 NotImplementedError 예외를 발생시키거나 로그 메시지를 출력하는 방식입니다.

새로운 기능을 구현하는 데 있어 중요한 부분은 해당 기능이 완전히 문서화되도록 보장하는 것입니다. 최소한 API 문서가 존재하도록 하는 것을 의미하지만, 사용 방법 안내서나 주제별 가이드를 추가해야 할 수도 있습니다.

새로운 기능 기여

개발 환경 설정

BeeWare에 기여하려면 개발 환경을 설정해야 합니다.

선행 조건

다음 필수 구성 요소를 설치해야 합니다.

BeeWare는 Python 3.10+이 필요합니다. 또한 가상 환경 관리 방법(예: venv)이 필요합니다.

설치된 Python 버전을 확인하려면 다음 명령어를 실행하세요:

Python 3.8.10 (기본, 2020년 7월 20일, 16:16:00)

여러 버전의 Python이 설치된 경우, python3를 특정 버전 번호(예: python3.13)로 대체해야 할 수 있습니다.

최근에 출시된 Python 버전(예: 3.14.0과 같이 ".0" 또는 ".1" 마이크로 버전 번호를 가진 버전)은 사용하지 않는 것이 좋습니다. 이는 macOS에서 Python을 지원하기 위해 필요한 도구가 최근 출시된 안정 버전용으로는 일반적으로 제공되지 않거나 지연되기 때문입니다.

BeeWare는 Python 3.10+이 필요합니다. 또한 가상 환경 관리 방법(예: venv)이 필요합니다.

설치된 Python 버전을 확인하려면 다음 명령어를 실행하세요:

Python 3.8.10 (기본, 2020년 7월 20일, 16:16:00)

여러 버전의 Python이 설치된 경우, python3를 특정 버전 번호(예: python3.13)로 대체해야 할 수 있습니다.

최근에 출시된 Python 버전(예: 3.14.0과 같이 ".0" 또는 ".1" 마이크로 버전 번호를 가진 버전)은 사용하지 않는 것이 좋습니다. 이는 Linux에서 Python을 지원하기 위해 필요한 도구가 최근 출시된 안정판 Python 버전에 대해 일반적으로 제공되지 않거나 지연되기 때문입니다.

BeeWare는 Python 3.10+이 필요합니다. 또한 가상 환경 관리 방법(예: venv)이 필요합니다.

설치된 Python 버전을 확인하려면 다음 명령어를 실행하세요:

C:\...>py -3 --version

여러 버전의 Python이 설치된 경우, -3를 특정 버전 번호(예: -python3.13)로 대체해야 할 수 있습니다.

최근에 출시된 Python 버전(예: 3.14.0과 같이 ".0" 또는 ".1" 마이크로 버전 번호를 가진 버전)은 피하는 것이 좋습니다. 이는 Windows에서 Python을 지원하기 위해 필요한 도구가 최근 출시된 안정판 Python 버전에 대해 일반적으로 제공되지 않거나 지연되기 때문입니다.

개발 환경 설정하기

BeeWare 개발 환경을 설정하는 권장 방법은 가상 환경을 사용한 후, BeeWare의 개발 버전과 그 종속성을 설치하는 것입니다.

BeeWare 저장소를 복제하세요

다음으로 GitHub의 BeeWare 페이지로 이동하여, 아직 하지 않았다면 저장소를 포크하여 본인 계정에 복제하세요. 다음으로, 포크한 페이지에서 "<> 코드" 버튼을 클릭하세요. 컴퓨터에 GitHub 데스크톱 애플리케이션이 설치되어 있다면 "GitHub 데스크톱으로 열기"를 선택할 수 있습니다. 그렇지 않은 경우 제공된 HTTPS URL을 복사한 후 명령줄을 사용하여 해당 URL로 저장소를 컴퓨터에 복제하세요:

BeeWare 저장소를 포크한 후 다음을 수행하세요:

$ git clone https://github.com/<사용자 이름>/beeware.git

(GitHub 사용자 이름을 대체)

BeeWare 저장소를 포크한 후 다음을 수행하세요:

$ git clone https://github.com/<사용자 이름>/beeware.git

(GitHub 사용자 이름을 대체)

BeeWare 저장소를 포크한 후 다음을 수행하세요:

C:\...>git clone https://github.com/<사용자 이름>/beeware.git

(GitHub 사용자 이름을 대체)

업스트림 저장소 설정

포크를 복제한 후 BeeWare 저장소를 upstream 원격 저장소로 추가하세요. 이렇게 하면 로컬 복제본이 원본 저장소를 참조하게 되어 시간이 지남에 따라 업데이트를 동기화하기가 더 쉬워집니다.

또한 Toga나 Briefcase 같은 도구가 정확한 버전 번호를 확인할 수 있도록 upstream에서 태그가 필요합니다:

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

포크에 해당 태그도 포함시키고 싶다면, 해당 태그를 푸시할 수 있습니다:

$ git push --tags

나중에 새로 복제본을 생성할 때 포크에서 태그를 사용할 수 있도록 하려면 이 방법이 유용할 수 있습니다.

가상 환경 생성

가상 환경을 설정하고 pip를 업그레이드하려면 다음을 실행하십시오:

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

이제 프롬프트 앞에 (.venv) 접두사가 붙어 있어야 합니다.

설치 BeeWare

이제 소스 코드를 확보했으므로, 개발 환경에 (https://setuptools.pypa.io/en/latest/userguide/development_mode.html)을 [editable install]BeeWare할 수 있습니다. 다음 명령어를 실행하세요:

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

프리커밋 활성화

BeeWare는 pre-commit이라는 도구를 사용하여 간단한 문제를 식별하고 코드 서식을 표준화합니다. 이는 git 커밋을 최종 확정하기 전에 일련의 코드 린터를 자동으로 실행하는 git 훅을 설치함으로써 이루어집니다. pre-commit을 활성화하려면 다음 명령을 실행하세요:

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

이제 BeeWare 해킹을 시작할 준비가 되었습니다!

브랜치에서 작업하기

변경 작업을 시작하기 전에 브랜치를 생성했는지 확인하세요. 기본적으로 저장소 포크를 복제하면 main 브랜치에서 작업하게 됩니다. 이는 BeeWare의 main 브랜치를 직접 복제한 것입니다.

main 브랜치에서 풀 리퀘스트를 제출할 수는 있지만, 하지 않는 것이 바람직합니다. 거의 완벽한 풀 리퀘스트를 제출하면, 검토하는 핵심 팀원이 사소한 변경을 요청하는 피드백을 주는 대신 필요한 수정을 직접 할 수 있습니다. 그러나 main 브랜치에서 풀 리퀘스트를 제출하면 검토자가 수정을 할 수 없게 됩니다.

메인 브랜치에서 작업하면 첫 번째 풀 리퀘스트를 완료한 후 본인에게도 어려움이 생깁니다. 두 번째 풀 리퀘스트를 진행하려면 두 번째 기여의 기반이 될 상위 프로젝트 메인 브랜치의 "깨끗한" 복사본이 필요합니다. 첫 번째 기여를 main 브랜치에서 수행했다면 더 이상 그 깨끗한 버전을 사용할 수 없게 됩니다.

대신 변경 사항은 기능 브랜치에서 수행해야 합니다. 기능 브랜치는 변경 사항을 식별할 수 있는 간단한 이름을 가집니다. 예를 들어, Windows 11에서 빌드 문제를 일으키는 버그를 수정하는 경우 fix-win11-build. 기능 브랜치를 생성할 수 있습니다. 해당 버그가 보고된 특정 이슈와 관련된 경우, 브랜치 이름에 해당 이슈 번호를 참조하는 것도 일반적입니다(예: fix-1234).

fix-win11-build 기능 브랜치를 생성하려면 다음을 실행하세요:

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
범위 확대를 피하십시오

"범위 확대"는 단일 기여로 해결되는 문제 목록이나 구현되는 기능이 작업 시작 시 의도했던 범위를 크게 벗어날 때 발생합니다. 간단한 이슈로 시작했는데, 밀접하게 관련된 문제를 발견하고 그 수정도 포함하기로 결정합니다. 그러다 세 번째 문제가… 어느새 5개의 이슈를 해결하고 3개의 새 기능을 추가하며 수십 개의 파일을 포함하는 풀 리퀘스트가 완성됩니다.

범위 확대는 누구에게나 발생합니다. 이는 노련한 개발자들에게 너무나도 익숙한 개념입니다. 우리 모두 여러 번 경험했고, 그로 인해 발생하는 모든 문제점도 겪어봤습니다.

범위 확대를 피해야 하는 매우 실용적인 이유가 있습니다. 기여물이 커질수록 작업하기가 더 어려워집니다. 경계 사례나 잠재적 문제를 식별하기가 더 어려워지므로, 기여물의 전반적인 품질이 저하될 수 있습니다. 리뷰어들이 서로 관련성이 없을 수 있는 여러 맥락을 처리해야 할 때 리뷰 작업도 더 어려워집니다. 기여 규모가 커질수록 리뷰 코멘트도 증가하며, 기여자로서 여러 리뷰 스레드를 추적하기 어려워질 수 있습니다. GitHub 사용 경험도 저하됩니다. PR 규모가 커질수록 GitHub UI가 느려져, GitHub 인터페이스를 통해 파일을 탐색하거나 리뷰 코멘트를 남기기가 점점 더 어려워집니다.

원본 제안서나 버그 보고서에 명시적으로 포함되지 않은 내용을 기여물에 추가할 이유가 생길 때마다, 범위 확대(scope creep)로 이어질 수 있는지 고려해야 합니다. 두 가지 별개의 기능을 분리하여 구현할 수 있는가? 알려진 제한사항이나 버그를 감수하고 기능을 구현한 후, 후속 풀 리퀘스트에서 해당 버그를 수정할 수 있는가? 버그 수정 작업의 일부가 다른 부분과 독립적으로 수행될 수 있는가? 변경 사항의 일부를 제외해도 원래 기여물에 영향을 미치지 않는다면, 그 부분은 제외하는 것이 바람직하다.

소프트웨어 개발은 항상 점진적인 개선의 과정입니다. 각 개별 기여는 병합 결과 코드 베이스가 더 나은 상태가 되어야 하지만, 버그나 기능의 일부를 향후 개선을 위한 과제로 남겨두는 것은 완전히 허용됩니다. 이는 풀 리퀘스트를 독립적으로 검토할 수 있는 여러 부분으로 나누거나, 다른 사람이 문제를 조사하고 해결할 수 있도록 이슈를 등록하는 것을 의미할 수 있습니다.

각 기여의 범위를 제한하는 것은 여러분을 포함한 모든 관련자에게 도움이 됩니다. 검토자분들, 심지어 여러분 스스로도 이를 높이 평가할 것입니다.

새로운 기능을 구현하십시오

버그를 수정하거나 기능을 구현하려면 새로운 코드를 작성해야 합니다.

BeeWare용 코드 작성 지침을 정리한 코드 스타일 가이드가 마련되어 있습니다.

테스트 주도 개발

코드가 의도한 대로 동작하는지 확인하는 좋은 방법은 먼저 해당 기능을 테스트할 테스트 케이스를 작성하는 것입니다. 테스트 대상 코드가 아직 구현되지 않았기 때문에, 이 테스트 케이스는 처음에는 실패해야 합니다. 그런 다음 테스트가 통과되도록 필요한 코드 수정을 가하면, 작성한 코드가 의도한 문제를 해결하고 있음을 확인할 수 있습니다.

코드를 실행하세요

코드를 작성한 후에는 제대로 실행되는지 확인해야 합니다. 코드를 직접 실행하여 예상한 대로 동작하는지 검증해야 합니다. 아직 하지 않았다면, 변경 사항에 대한 테스트 케이스를 작성하는 것이 좋습니다. 앞서 언급했듯이, 코드가 주석 처리되었거나 존재하지 않을 경우 이 테스트는 실패해야 합니다.

테스트 케이스를 테스트 스위트에 추가하면 다른 테스트들과 함께 실행할 수 있습니다. 다음 단계는 테스트 스위트를 실행하는 것입니다.

테스트 실행 및 커버리지

BeeWare는 테스트 프로세스를 관리하기 위해 tox를 사용하고, 자체 테스트 스위트에는 pytest를 사용합니다.

기본 tox 명령어에는 다음 작업이 포함됩니다:

  • 커밋 전 훅
  • towncrier 릴리스 노트 확인

  • 문서 코드 검사

  • 사용 가능한 Python 버전을 위한 테스트 모음

  • 코드 커버리지 보고

이것이 바로 풀 리퀘스트를 제출할 때 CI에서 실행되는 작업의 핵심입니다.

전체 테스트 모음을 실행하려면 다음 명령을 실행하십시오:

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

전체 테스트 스위트를 실행하는 데는 시간이 다소 걸릴 수 있습니다. tox을 병렬로 실행하거나 tox p (또는 tox run-parallel)을 실행하면 속도를 상당히 높일 수 있습니다. 테스트 스위트를 병렬로 실행하면 진행 상황에 대한 피드백은 줄어들지만, 테스트 실행이 끝난 후에는 발견된 문제에 대한 요약 정보를 여전히 확인할 수 있습니다. 테스트가 실행되었음을 나타내는 출력 결과가 표시되어야 합니다. SKIPPED 테스트가 표시될 수는 있지만, FAIL 또는 ERROR 테스트 결과는 절대 나타나지 않아야 합니다. 우리는 모든 패치를 병합하기 전에 전체 테스트 스위트를 실행합니다. 이 과정에서 문제가 발견되면 해당 패치는 병합하지 않습니다. 만약 테스트 오류나 실패를 발견했다면, 테스트 환경에 문제가 있거나 우리가 이전에 보지 못했던 극단적인 사례를 발견한 것입니다. 어느 쪽이든 저희에게 알려주세요!

테스트가 통과되는 것 외에도, 100% 테스트 커버리지가 보고되어야 합니다.

테스트 변형 실행

여러 버전의 파이썬에 대해 테스트 실행하기

기본적으로 많은 tox 명령어는 BeeWare가 지원하는 각 Python 버전에 대해 한 번씩, 총 여러 번 테스트 스위트를 실행하려고 시도합니다. 하지만 이를 위해서는 각 Python 버전이 사용자의 컴퓨터에 설치되어 있어야 하며, tox의 Python 탐색 프로세스에서 이를 감지할 수 있어야 합니다. 일반적으로, 특정 Python 버전이 PATH를 통해 사용 가능한 경우, tox는 이를 찾아서 사용할 수 있어야 합니다.

테스트 스위트만 실행

새로운 기능을 빠르게 반복 개발하고 있다면 전체 테스트 스위트를 실행할 필요는 없으며, 단순히 단위 테스트만 실행하면 됩니다. 이를 위해 다음 명령어를 실행하세요:

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

테스트의 일부만 실행하기

기본적으로 tox는 단위 테스트 모음에 포함된 모든 테스트를 실행합니다. 새로운 테스트를 개발할 때는 해당 테스트 하나만 실행하는 것이 유용할 수 있습니다. 이를 위해 pytest에 [임의의 (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run) 지정자]tox를 인수로 전달할 수 있습니다. 이러한 테스트 경로는 briefcase 디렉터리를 기준으로 합니다. 예를 들어, 단일 파일에 포함된 테스트만 실행하려면 다음 명령을 실행하세요:

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

테스트 스위트의 일부만 실행하더라도 커버리지 보고서는 여전히 생성되지만, 커버리지 결과에는 실행한 특정 테스트에서 실제로 실행된 코드 줄만 표시됩니다.

특정 Python 버전에 대한 테스트 모음을 실행합니다

기본적으로 tox -e py는 사용자의 컴퓨터에서 python로 해석되는 인터프리터를 사용하여 실행됩니다. 여러 버전의 파이썬이 설치되어 있고, 설치된 버전 중 특정 버전을 사용하여 테스트를 실행하려면 사용할 파이썬 버전을 명시적으로 지정할 수 있습니다. 예를 들어, 파이썬 3.10에서 테스트 모음을 실행하려면 다음 명령을 실행하십시오:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

명령줄에 --와 테스트 사양을 추가하면 테스트 집합을 실행할 수 있습니다.

커버리지 분석 없이 테스트 스위트 실행 (빠름)

기본적으로 tox는 단일 스레드 모드에서 pytest 테스트 스위트를 실행합니다. 테스트 스위트를 병렬로 실행하면 실행 속도를 높일 수 있습니다. 이 모드는 생성된 프로세스 내에서 커버리지를 캡처하는 것이 복잡하기 때문에 커버리지 파일을 생성하지 않습니다. 단일 Python 버전을 "fast" 모드로 실행하려면 다음 명령을 실행하십시오:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

명령줄에 --와 테스트 사양을 추가하면 테스트의 일부를 실행할 수 있으며, 테스트 대상에 버전을 추가하면 특정 Python 버전을 사용할 수 있습니다(예: Python py310-fast에서 fast를 실행하려면 3.10를 추가).

코드 커버리지

BeeWare는 코드베이스에서 100%의 브랜치 커버리지를 유지하고 있습니다. 프로젝트에서 코드를 추가하거나 수정할 때는, 변경 사항이 모두 테스트를 통과하도록 테스트 코드를 반드시 추가해야 합니다.

그러나 BeeWare는 여러 플랫폼과 다양한 Python 버전을 대상으로 하므로, 단일 플랫폼 및 Python 버전에서만으로는 전체 커버리지를 검증할 수 없습니다. 이를 해결하기 위해 tool.coverage.coverage_conditional_plugin.rules의 pyproject.toml 섹션에는 여러 조건부 커버리지 규칙이 정의되어 있습니다(예: no-cover-if-is-windows는 Windows에서 테스트 스위트를 실행할 때 실행되지 않는 코드 블록을 표시하는 데 사용할 수 있습니다). 이러한 규칙은 특정 플랫폼이나 Python 버전에서만 커버되는 코드 섹션을 식별하는 데 사용됩니다.

특히, 서로 다른 Python 버전을 사용해 커버리지 보고서를 작성할 경우 다소 예기치 않은 결과가 발생할 수 있습니다. 예를 들어, 커버리지 파일을 생성할 때는 특정 버전의 Python을 사용했으나 보고서를 생성할 때는 다른 버전을 사용한 경우, 보고서에 누락된 분기에 대한 오탐이 포함될 수 있습니다. 따라서 커버리지 보고서를 작성할 때는 항상 커버리지 파일을 생성하는 데 사용된 Python 버전 중 가장 오래된 버전을 사용해야 합니다.

보장 범위 결과 이해하기

커버리지 테스트 출력물의 마지막 부분에는 수집된 커버리지 데이터에 대한 보고서가 나와야 합니다:

이름    명세서   미결제 지점   부분결제   대납   누락
 ---------------------------------------------------
 합계    7540 0   1040 0  100.0%

이는 테스트 스위트가 코드 내의 모든 가능한 분기 경로를 실행했음을 의미합니다. 이것이 버그가 전혀 없다는 것을 100% 보장하는 것은 아니지만, 코드베이스의 모든 코드 줄을 실제로 테스트하고 있다는 뜻입니다.

코드베이스에 변경 사항을 적용하면 커버리지에 공백이 생길 수 있습니다. 이런 경우 커버리지 보고서를 통해 어떤 줄이 실행되지 않는지 확인할 수 있습니다. 예를 들어, some/interesting_file.py에 새로운 로직을 추가하는 변경을 가했다고 가정해 봅시다. 커버리지 보고서는 다음과 같이 표시될 수 있습니다:

이름 문장 수   누락 분기 BrPart  커버   누락
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 총계 7540 1   1726 0  99.9%

이는 170행, 302~307행, 그리고 320행에서 335행으로 이동하는 분기문이 테스트 스위트에 의해 실행되지 않고 있음을 의미합니다. 이 커버리지를 복원하려면 새로운 테스트를 추가하거나 기존 테스트를 수정해야 합니다.

호스트 플랫폼 및 Python 버전에 대한 지원 현황 보고서

사용 중인 플랫폼과 Python 버전에 대한 커버리지 보고서를 생성할 수 있습니다. 예를 들어, 테스트 스위트를 실행하고 Python 3.10에 대한 커버리지 보고서를 생성하려면 다음 명령을 실행하세요:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

호스트 플랫폼에 대한 커버리지 보고서

tox에서 지원되는 모든 Python 버전을 사용할 수 있다면, 다음 명령을 실행하여 호스트 플랫폼에 대한 커버리지 결과를 확인할 수 있습니다:

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

HTML 형식의 보도 내용

커버리지 -html 환경 이름 뒤에 tox를 추가하면 HTML 커버리지 보고서를 생성할 수 있습니다. 예를 들어:

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

단순히 테스트를 작성하는 것만이 전부가 아닙니다!

비록 우리가 모든 코드를 철저히 테스트하고는 있지만, 이 작업은 단순히 그 수준의 테스트를 유지하는 데 그치는 것이 아닙니다. 작업의 일부는 개발 과정에서 코드를 지속적으로 점검하는 것입니다. 콘크리트 구명조끼를 위한 포괄적인 테스트 세트를 작성할 수는 있겠지만… 그런 구명조끼는 본래의 용도에는 여전히 쓸모가 없을 테니까요!

테스트를 개발할 때는 핵심 모듈이 내부적으로도 일관성을 유지하는지 확인해야 합니다. 내부적으로 일관성이 없는 메서드 이름(예: 한 모듈에서는 on_select이라고 불리지만 다른 모듈에서는 on_selected이라고 불리는 경우)이나 데이터가 일관성 없이 처리되는 부분을 발견하면, 이를 표시해 두고 티켓을 생성하여 저희에게 알려주십시오. 또는 해결 방법을 확실히 알고 있다면, 발견한 문제를 수정하는 풀 리퀘스트를 생성해 주십시오.

문서 작성

BeeWare'의 문서에 변경 사항을 적용하기 전에 기존 문서를 빌드할 수 있는지 확인하는 것이 좋습니다.

Python 3.13 인터프리터가 설치되어 있고 경로에 접근 가능해야 합니다(즉, python3.13 명령어가 Python 3.13 인터프리터를 실행해야 함).

BeeWare는 문서 생성에 tox를 사용합니다. 다음 tox 명령어는 프로젝트 루트 디렉토리에 위치한 tox.ini 파일과 동일한 위치에서 실행해야 합니다.

라이브 문서 미리보기

문서 편집을 신속하게 지원하기 위해 BeeWare에는 "실시간 미리보기" 모드가 있습니다.

라이브 미리보기는 경고와 함께 빌드됩니다!

라이브 서버는 문서 업데이트를 반복 작업하는 데 사용할 수 있습니다. 업데이트 과정에서 마크업 문제가 발생할 수 있습니다. WARNING로 표시된 문제는 표준 빌드를 실패하게 하지만, 라이브 서버는 콘솔 출력에 경고를 표시하면서 빌드를 계속하도록 설정되어 있습니다. 이를 통해 라이브 미리보기를 재시작하지 않고도 반복 작업을 수행할 수 있습니다.

WARNING는 ERROR와 다릅니다. ERROR로 간주되는 문제를 도입하면 라이브 서버가 실패하고 재시작이 필요합니다. WARNING 문제가 해결될 때까지 다시 시작되지 않습니다.

라이브 서버를 시작하려면:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

이 명령은 문서를 빌드하고, 문서를 제공하기 위해 웹 서버를 시작하며, 문서 소스 파일에 대한 변경 사항을 감시합니다.

서버가 시작되면 콘솔 출력에 다음과 같은 내용이 표시됩니다:

정보    -  [11:18:51] http://127.0.0.1:8000/에서 서비스 중

브라우저를 열고 제공된 URL로 이동하세요. 이제 문서 작업을 반복할 수 있습니다. 변경 사항이 감지되면 문서가 재구축되며, 수정된 페이지를 보고 있는 모든 브라우저가 자동으로 새로 고쳐집니다.

docs-live는 초기 단계입니다

docs-live을 실행하여 라이브 서버와 작업하는 것은 초기 반복 작업을 위한 것입니다. 풀 리퀘스트를 제출하기 전에 항상 로컬 빌드를 실행해야 합니다.

로컬 빌드

반복 작업을 완료한 후에는 문서의 로컬 빌드를 수행해야 합니다. 이 빌드 프로세스는 마크업 문제가 있을 경우 실패하도록 설계되었습니다. 이를 통해 라이브 서버에서는 놓쳤을 수 있는 모든 문제를 포착할 수 있습니다.

로컬 빌드 생성

로컬 빌드를 생성하려면:

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

이 빌드의 출력은 프로젝트 루트 디렉토리의 _build 디렉토리에 생성됩니다.

로컬 번역 빌드 생성

BeeWare's 문서가 여러 언어로 번역됩니다. 영어 문서의 업데이트는 다른 언어 빌드에서 문제를 일으킬 수 있습니다. 풀 리퀘스트를 제출하기 전에 모든 빌드가 정상 작동하는지 확인하는 것이 중요합니다.

사용 가능한 모든 번역에 대한 빌드를 생성하려면:

(동사) $ tox -e docs-all

(동사) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

각 언어 빌드의 결과물은 해당 _build/html/<languagecode> 디렉터리에 저장됩니다. 여기서 <languagecode>는 특정 언어에 할당된 2자리 또는 5자리 언어 코드입니다(예: 프랑스어는 fr, 이탈리아어는 it 등).

단일 빌드에서 문제를 발견한 경우, tox -e docs-<languagecode>를 실행하여 해당 개별 빌드를 따로 실행할 수 있습니다. 예를 들어, 프랑스어 문서만 빌드하려면 다음을 실행하세요:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

단일 언어 빌드의 출력은 _build 디렉터리에 생성됩니다.

문서 린팅

빌드 프로세스는 마크다운 문제를 식별하지만, BeeWare는 스타일과 서식을 위한 추가 검사를 수행하며 이를 "린팅"이라고 합니다. 린팅 검사를 실행하려면:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

이것은 문서에 다음이 포함되어 있지 않음을 검증합니다:

  • 깨진 하이퍼링크
  • 맞춤법이 틀린 단어

단어의 올바른 철자가 오타로 식별되면 해당 단어를 docs/spelling_wordlist 안에 있는 목록에 추가하십시오. 이렇게 하면 해당 단어가 맞춤법 검사기 사전에 추가됩니다. 이 목록에 추가할 때 다음 사항을 기억하십시오:

  • 미국식 철자를 선호하며, 프로그래밍 특유의 관용적 표현(예: "apps")과 명사의 동사화(예: "scrollable")에 대해서는 일부 유연성을 허용합니다.
  • 제품명에 대한 모든 언급은 해당 제품의 권장 대소문자 표기법을 사용해야 합니다. (예: "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • 어떤 용어가 "암호"로 사용되고 있다면, 사전(dictionary)에 추가하기보다는 리터럴(like this)로 인용해야 합니다.
문서 작성

(.venv) C:...>tox -e coverage-platform-html

기존 문서 업데이트

기존 문서를 편집하는 경우 /docs/en 디렉터리에서 파일을 찾아야 합니다. 파일 구조는 페이지 구조를 따르므로 문서 URL을 사용하여 파일을 찾을 수 있습니다.

새 문서 추가

새 문서를 추가하는 경우 몇 가지 추가 단계가 필요합니다.

문서는 docs/en 디렉토리 내 적절한 위치에 생성해야 합니다. 설명을 위해, 파일명 new_doc.md로 새 문서를 추가한다고 가정하겠습니다.

그런 다음, 새 파일을 포함하도록 docs/en/SUMMARY.md 파일을 업데이트해야 합니다. SUMMARY.md는 기본적으로 docs/en 디렉터리 구조를 반영하도록 구성되어 있지만, 더 중요한 것은 왼쪽 사이드바의 구조를 직접 결정한다는 점입니다. new_doc.md를 포함하려는 섹션을 찾았을 때, 와일드카드 경로가 나열되어 있다면 SUMMARY.md에서 아무것도 변경할 필요가 없습니다. 예를 들어:

- ./디렉터리 경로/*

new_doc.md를 포함하려는 섹션이 개별 마크다운 링크 목록인 경우, 해당 링크를 명시적으로 추가해야 합니다. 예를 들어:

- [내 새 문서](new_doc.md)

문서 작성하기

이제 원하는 파일을 편집기로 열어 글을 쓰기 시작할 수 있습니다.

BeeWare 문서 작성 지침을 설명하는 문서 스타일 가이드이 마련되어 있습니다.

변경 사항을 추가하세요

많은 BeeWare 도구는 각 릴리스의 릴리스 노트를 작성하는 데 towncrier를 사용합니다. 해당 도구 중 하나에 풀 리퀘스트를 제출할 때는 변경 사항 설명을 포함해야 합니다. 이 변경 사항 설명은 릴리스 노트에 포함되어 수행된 변경 사항을 설명하는 항목이 됩니다.

모든 풀 리퀘스트에는 changes/ 디렉터리에 최소 한 개의 파일이 포함되어야 하며, 해당 파일은 풀 리퀘스트로 구현된 변경 사항에 대한 간략한 설명을 제공해야 합니다. 변경 노트는 마크다운 형식으로 작성되어야 하며, 파일 이름은 <id>.<fragment type>.md 형식을 따라야 합니다. 제안하는 변경 사항이 기존 이슈 번호가 있는 버그 수정 또는 기능 구현인 경우, 해당 티켓 번호를 ID로 사용합니다. 해당 변경 사항에 대응하는 이슈가 없는 경우, PR 번호를 ID로 사용할 수 있습니다. 이 PR 번호는 풀 리퀘스트를 푸시하기 전까지는 알 수 없으므로, 첫 번째 CI 통과 시 towncrier 검사가 실패할 것입니다. 변경 사항 설명을 추가하고 PR 업데이트를 푸시하면 CI가 통과될 것입니다.

다섯 가지 조각 유형이 있습니다:

  • feature: 이 PR은 이전에는 불가능했던 새로운 동작이나 기능을 추가합니다(예: 새로운 패키징 형식 지원 추가, 기존 패키징 형식의 새 기능 추가);
  • bugfix: 이 PR은 기존 구현체의 버그를 수정합니다;
  • PR은 문서화에 상당한 개선을 가져왔습니다;
  • removal; 이 PR은 BeeWare API에서 하위 호환성이 없는 변경 사항을 나타냅니다; 또는
  • misc; 릴리스 노트에 공지할 필요가 없는 사소한 변경 또는 관리적 변경(예: 오타 수정, 사소한 언어적 명확화, 종속성 버전 업데이트 등).

변경 노트의 이 설명은 사용자의 관점에서 변경 사항에 대한 고수준의 "마케팅" 요약이어야 하며, 심층적인 기술적 설명이나 구현 세부사항이 아닙니다. 이는 커밋 메시지와 구별됩니다. 커밋 메시지는 향후 개발자가 변경 사유를 추적할 수 있도록 수행된 작업을 설명하는 반면, 변경 노트는 내부 구조에 대한 지식이 없을 수 있는 사용자를 위한 설명입니다.

예를 들어, 프로젝트 이름 지정과 관련된 버그를 수정했다면 커밋 메시지는 다음과 같을 수 있습니다:

숫자로 시작하는 프로젝트 이름을 허용하지 않도록 더 강력한 정규 표현식 검사를 적용하십시오.

해당 변경 노트는 다음과 같이 작성될 것입니다:

프로젝트 이름은 더 이상 숫자로 시작할 수 없습니다.

일부 PR은 여러 기능을 도입하고 여러 버그를 수정하거나, 여러 하위 호환성 없는 변경 사항을 도입할 수 있습니다. 이 경우 PR에는 여러 개의 변경 사항 설명 파일이 있을 수 있습니다. 동일한 ID로 두 개의 조각 유형을 연결해야 하는 경우 숫자 접미사를 추가할 수 있습니다. 예를 들어, PR 789가 티켓 123에 설명된 기능을 추가하고 티켓 234에 설명된 버그를 해결하며 두 가지 하위 호환성 없는 변경 사항을 수행한 경우, 다음과 같이 총 4개의 변경 사항 설명 파일이 있을 수 있습니다:

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

towncrier 및 조각 유형에 대한 자세한 내용은 뉴스 조각을 참조하십시오. 또한 changes 저장소의 BeeWare 디렉터리에서 기존 뉴스 조각 예시를 확인할 수 있습니다. 이 폴더가 비어 있다면, BeeWare가 최근 새 릴리스를 발표한 탓일 가능성이 높습니다. 변경 사항 노트 파일은 삭제되고 통합되어 각 릴리스마다 릴리스 노트를 업데이트합니다. 필요한 주석 스타일을 확인하려면 해당 파일을 참조하십시오. 변경 사항 노트 서식 방법은 최근 병합된 PR을 참고하십시오.

풀 리퀘스트 제출

이제 모든 변경 사항을 커밋했으니 풀 리퀘스트를 제출할 준비가 되었습니다. 원활한 검토 과정을 보장하기 위해 취해야 할 몇 가지 단계가 있습니다.

프리커밋 작업

변경 사항을 커밋할 때 pre-commit이 자동으로 실행됩니다. 커밋에 문제가 발견되면 커밋이 실패하게 됩니다. 가능한 경우 pre-commit은 발견된 문제를 수정하기 위해 필요한 변경을 수행합니다. 다음 예시에서는 ruff 검사로 코드 포맷팅 문제가 발견되었습니다:

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

이 경우 ruff가 자동으로 문제를 해결했습니다. 따라서 프리커밋 검사 결과 수정된 파일을 다시 추가하고 변경 사항을 재커밋할 수 있습니다. 다만 일부 검사는 수동 수정이 필요할 수 있습니다. 해당 수정을 완료한 후 수정된 파일을 다시 추가하고 재커밋하십시오.

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

모든 작업이 완료되면 커밋이 최종 확정되었다는 메시지가 표시되며, git log에서 해당 커밋이 가장 최근에 추가된 항목으로 나타납니다. 이제 GitHub에 푸시할 준비가 되었습니다.

변경 사항을 GitHub에 푸시하고 풀 리퀘스트를 생성하세요

GitHub에 처음 푸시할 때, 새 풀 리퀘스트를 생성할 수 있는 GitHub 페이지로 바로 연결되는 URL이 제공됩니다. 해당 URL을 따라가서 풀 리퀘스트를 생성하세요.

다음은 push에서 예상되는 내용의 예시이며, URL이 강조 표시되어 있습니다.

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

현재 브랜치를 GitHub에 이미 푸시한 경우 해당 URL을 다시 받지 못합니다. 그러나 PR 생성 URL에 접근할 수 있는 다른 방법이 있습니다:

  • 업스트림 저장소로 이동한 후, "풀 리퀘스트"를 클릭하고 "새 풀 리퀘스트"를 선택한 다음, 풀 리퀘스트를 제출할 원본 브랜치를 선택하세요.
  • 최근에 푸시했다면, 업스트림 저장소로 이동하여 파일 목록 위에 있는 "최근 푸시됨"을 나타내는 배너를 찾은 후 "비교 및 풀 리퀘스트" 버튼을 클릭하세요.
  • GitHub CLI gh pr create 명령어를 사용하고 프롬프트에 입력하세요.
  • GitHub CLI gh pr create --web 명령어를 사용하여 웹 브라우저를 열고 PR 생성 페이지로 이동합니다.

이 중 어떤 옵션을 선택하더라도 새 풀 리퀘스트를 생성할 수 있습니다.

GitHub CLI: gh

GitHub는 터미널에서 (https://cli.github.com/) 명령어를 통해 GitHub의 다양한 기능에 접근할 수 있는 [GitHub CLI]gh를 제공합니다. GitHub CLI 문서에는 모든 기능이 설명되어 있습니다.

풀 리퀘스트 내용

풀 리퀘스트 제목은 정보가 풍부하고 명확하며 간결해야 합니다. 가능하면 짧게 유지하되, 필요한 경우 긴 제목도 허용됩니다. 좋은 PR 제목은 아무런 배경 지식이 없는 사람에게도 해당 PR이 어떤 버그를 수정하거나 어떤 기능을 구현하는지 상당히 확실하게 알려줄 수 있어야 합니다.

PR 설명은 PR의 변경 사항을 명확히 반영해야 합니다. 아무런 배경 지식이 없는 사람도 설명을 읽고 변경 사유를 비교적 완벽하게 이해할 수 있어야 합니다. 농담, 관용구, 구어체 표현, 그리고 대문자만 사용하거나 과도한 구두점을 사용하는 등 불필요한 서식 사용은 피하십시오. 이는 PR에서 발생하는 내용을 직설적으로 설명하기 위한 것이며, 이러한 요소들을 배제함으로써 다른 사람들이 설명을 더 쉽게 이해할 수 있게 됩니다.

PR에 포함된 변경 사항에 아직 포함되지 않은 재현 사례나 사용한 테스트 절차가 있다면, 이를 설명하고 PR에 포함해야 합니다. 설명에는 해당 절차의 실행 방법과 원하는 결과를 재현하기 위한 조치 사항이 포함되어야 합니다.

풀 리퀘스트가 이슈 #1234를 해결할 경우, 풀 리퀘스트 설명에 Fixes #1234 텍스트를 포함해야 합니다. 이렇게 하면 풀 리퀘스트가 병합될 때 해당 이슈가 자동으로 닫힙니다. 동일한 #1234 구문을 사용하여 다른 토론, 이슈 또는 풀 리퀘스트를 참조할 수 있습니다. 다른 저장소의 이슈를 참조하려면 번호 앞에 -를 붙입니다. 예를 들어 python/cpython#1234는 CPython 저장소의 이슈 1234를 참조합니다.

지속적 통합

지속적 통합(CI)은 풀 리퀘스트에 대한 자동화된 검사를 실행하는 과정입니다. 여기에는 코드 포맷팅이 올바른지 확인하는 것과 같은 간단한 검사부터 테스트 스위트 실행 및 문서 빌드까지 포함됩니다.

CI 실패를 유발할 수 있는 변경 사항은 다양합니다. 대체로 CI를 통과하지 못하는 PR은 검토하지 않습니다. 풀 리퀘스트를 생성한 후 CI가 실패할 경우, 통과될 때까지 검토를 시작하지 않습니다. 변경 사항으로 인해 실패가 발생하면 그 원인을 조사하고 문제를 해결하는 것은 귀하의 책임입니다.

CI가 실패하면, 실패한 링크들이 PR 페이지 하단 "일부 검사가 성공하지 못했습니다" 제목 아래에 표시됩니다. 실패한 검사의 목록이 표시되며, 통과한 검사도 있을 경우 이 목록은 전체 검사 목록 상단에 위치합니다. 실패 링크를 클릭하면 로그로 이동합니다. 로그에는 실패 원인을 파악하는 데 필요한 모든 정보가 포함되어 있는 경우가 많습니다. 로그를 꼼꼼히 읽고 실패 원인을 파악한 후, 해결을 위해 필요한 조치를 취하세요.

가끔 CI 검사가 여러분의 변경 사항과 무관한 이유로 실패할 수 있습니다. 이는 CI 검사를 실행하는 머신의 문제 때문일 수도 있고, CI 검사가 불안정하기 때문일 수도 있습니다. 실패를 확인하고, 여러분의 변경 사항과 무관하다고 확신한다면, 해당 내용을 PR에 댓글로 남겨 주십시오. 저희가 확인하겠습니다.

새로운 CI 실행을 트리거하려면, 브랜치에 새로운 변경 사항을 푸시해야 합니다.

CI 통과에 도움이 필요한 상황이 발생하면, PR에 댓글을 남겨 알려주시기 바랍니다. 저희가 가능한 한 도움을 드리겠습니다.

pre-commit 및 towncrier 검사

pre-commit 또는 towncrier 검사가 실패할 경우, 나머지 대부분의 CI 검사 실행이 차단됩니다. 전체 검사 세트가 실행되려면 해당 문제를 해결해야 합니다.

CI 자원이 제한적입니다. 브랜치에 푸시할 때마다 CI가 실행된다는 점을 이해하는 것이 중요합니다. 여러 변경 사항을 적용할 계획이라면, 로컬에서 변경 사항을 모두 준비한 후 한 번에 푸시하는 것이 좋습니다. CI는 배치 내 가장 최근 커밋에 대해서만 실행되므로 CI 시스템에 가해지는 부하를 최소화할 수 있습니다.

PR 제출 과정은 CI를 통과하거나, 통과하지 못한 이유에 대한 설명을 제공할 때까지 완료되지 않습니다.