콘텐츠로 이동

새 이슈 제출

잘 작성된 문제 또는 버그 보고서는 문제 해결 능력에 큰 차이를 만들 수 있습니다. BeeWare에 효과적인 버그 보고서를 제출하는 방법은 다음과 같습니다.

기존 이슈 검색

새 이슈를 제출하기 전에, 기존 이슈 중 본인 문제와 일치하는 항목이 있는지 인덱스를 검색하십시오. 본인 문제와 유사해 보이는 기존 오픈 이슈가 있다면, 해당 이슈에 본인 경험에 대한 추가 정보를 댓글로 남겨 주십시오. 예를 들어, 다른 Python 버전이나 다른 운영 체제에서 문제가 발생하는 경우, 이러한 추가 정보는 문제의 영향 범위나 원인을 파악하는 데 도움이 될 수 있습니다.

닫힌 이슈 중 자신의 문제와 일치하는 것처럼 보이는 것이 있다면, 해당 이슈가 언제 닫혔는지 확인하세요. 이슈가 아주 최근에 닫혔다면, 이는 버그가 수정되었으며 다음 릴리스에서 해결될 가능성이 높습니다. 이슈가 4개월 이상 전에 닫혔다면, 아무리 오류 메시지가 비슷해 보여도 현재 겪고 있는 문제는 다른 문제일 가능성이 큽니다.

현재 보고 계신 현상과 일치하는 이슈를 찾지 못하셨다면, 새 이슈를 생성하는 것이 적절할 수 있습니다.

토론으로 시작하세요

GitHub에 이슈를 제출하기 전에, 먼저 토론을 시작하여 경험하고 있는 현상이 실제로 버그인지, 아니면 설정이나 프로세스상의 문제인지 물어보는 것을 고려해 보세요. 문서화된 동작과 직접적으로 상충되는 행동을 목격하지 않는 한, 버그 보고서를 바로 제출하기 전에 질문을 하는 것이 더 나을 수 있습니다. 만약 실제로 문제를 발견한 것으로 판명되면, 토론 주제를 쉽게 이슈로 전환할 수 있습니다.

토론 시작은 문제를 가장 적합한 장소에 보고하는 데도 도움이 될 수 있습니다. BeeWare 사용 중 문제를 경험했을 수 있지만, 해당 문제는 BeeWare 생태계 내 다른 프로젝트의 버그로 인해 발생했을 수도 있습니다.

좋은 버그 리포트 작성하기

새로운 이슈가 필요한 경우, 가능한 한 많은 세부 정보를 제공하는 것이 중요합니다. 좋은 버그 리포트에는 버그와 잠재적으로 관련된 모든 정보와 함께, 가능한 한 최소한의 재현 예시가 포함되어야 합니다.

재현 예제는 버그를 여전히 보여줄 수 있으면서도 가능한 한 짧고 간결해야 합니다. 방대한 예제를 제공하면 문제 해결이 훨씬 더 어려워지며, 특히 다른 라이브러리에 의존하거나 예제의 예상 동작이나 내부 논리에 대한 광범위한 지식이 필요한 경우에는 더욱 그렇습니다.

가능한 한 많은 세부 정보를 제공해 주셔야 합니다. 여기에는 다음 사항이 포함되지만, 이에 국한되지는 않습니다:

  • 운영 체제 버전 - 마이크로 버전까지 포함 (예: macOS 15.7.2).
  • 사용 중인 Python 버전, 마이크로 버전(예: 3.14.1)까지 포함하여.
  • 파이썬을 어떻게 설치했나요? python.org에서 다운로드했나요? Homebrew를 사용했나요? uv? pyenv? conda? 다른 방법을 사용했나요?
  • 사용 중인 BeeWare 도구들의 구체적인 버전(예: Toga 0.5.3)을 알려주세요. 개발 버전을 사용 중이라면 어떤 Git 해시를 사용하고 계신가요? "현재 메인 브랜치"라고만 말해선 안 됩니다. 이는 매일 변경될 수 있기 때문입니다.
  • 문제를 유발하기 위해 설치해야 하는 다른 패키지의 특정 버전. 이 정보를 제공하기 위해 python -m pip freeze 실행 결과를 포함할 수 있습니다.
  • 로그 파일이 생성된 경우, 전체 로그 파일.
  • 스택 트레이스가 생성된 경우, 전체 스택 트레이스를 제공하십시오. 최종 오류 메시지만 제공하지 마십시오. 스택 트레이스의 전체 컨텍스트가 중요합니다. 또한 이를 스크린샷이 아닌 텍스트 형식으로 제공하는 것이 가장 좋습니다.
  • 컴퓨터나 네트워크 설정에 문제가 영향을 미칠 수 있는 다른 요소가 있나요? 컴퓨터가 오래되었거나 느린 편인가요? 방화벽, 바이러스 검사 프로그램 또는 기타 제한 사항이 적용된 업무용 컴퓨터인가요? 네트워크 속도가 특히 느린가요? 운영 체제를 비정상적인 시스템 기본값(예: 매우 큰 글꼴 또는 기타 보조 기술 활성화)으로 실행하고 있나요?

상상력을 발휘해 보세요. 겪고 있는 문제에 영향을 미칠 수 있다고 생각되는 모든 것을 포함시키십시오. 필요한 것 이상을 제공해 주시면, 필요 없는 부분은 쉽게 제외할 수 있습니다. 누락된 부분은 우리가 생각해낼 수 없습니다.

최소한의 예시

버그 보고서의 가장 중요한 부분은 최소 재현 사례입니다. 제3자가 재현 사례에 대한 지침을 읽고, 해당 지침을 따라 동일한 문제를 관찰할 수 있어야 합니다. 이는 문제를 보여주는 샘플 프로젝트를 제공하는 것을 의미할 수 있으며, 더 나은 방법은 기존 예제(기존 코드베이스의 일부인 튜토리얼이나 예제 프로젝트 등)를 사용하는 것입니다.

전체 프로젝트는 최소 재현 사례가 아닙니다. 최소 재현 사례에는 문제 재현에 절대적으로 필요하지 않은 코드는 포함되어서는 안 됩니다. 재현 사례를 구성할 때는 냉정하게 접근하십시오. 버튼이 문제 재현에 필요하지 않다면, 그 버튼을 포함하지 마십시오.

최소 재현 사례를 개발하는 과정 자체가 문제의 근원을 밝혀내는 경우가 많습니다. 왜냐하면 최소 예시를 만드는 행위는 코드의 버그인지, 잘못된 가정이나 API 사용에서 비롯된 것인지 정확히 무엇이 문제를 일으키는지 파악하도록 강제하기 때문입니다.

재현 지침에서도 명확하게 설명해야 합니다. "예제 앱을 닫으세요"라는 표현은 창 닫기 버튼 클릭, 메뉴에서 "종료" 선택, 터미널에서 Control-C 입력 등 다양한 해석이 가능합니다. 문제 재현을 위해 수행해야 할 작업에 대해 보고서에 모호함이 없도록 해야 합니다.

보고서 제출

프로젝트 이슈 목록 이동하여 "새 이슈" 버튼을 클릭한 후 "버그 보고"를 선택하여 프로세스를 시작하세요.

문제 템플릿의 모든 항목을 반드시 작성해야 합니다. 템플릿은 필요한 정보를 제공하도록 안내하기 위한 것입니다. 템플릿에서 요구하는 정보보다 더 많은 정보를 제공할 수 있으며(그리고 그렇게 해야 합니다!), 최소한 템플릿에 포함된 모든 정보는 반드시 제공되어야 합니다.

코드를 포함할 때, BeeWare 튜토리얼과 같은 기존 예제로 재현할 수 있는 경우에는 링크를 제공할 수 있습니다. 그렇지 않은 경우에는 보고서에 코드를 직접 포함하십시오. 코드는 마크다운 형식으로 작성해야 하며, 코드 블록은 앞뒤로 세 개의 백틱(```)으로 둘러싸야 합니다.

긴 텍스트 블록을 포함해야 하는 경우, 다음 구문을 사용하여 접힌 콘텐츠로 만들 수 있습니다:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

가능한 한 많은 정보를 입력한 후 "생성"을 클릭하여 보고서를 제출하세요.