도구를 사용하여¶

우리가 얻을 수 있는 가장 가치 있는 피드백 중 하나는 BeeWare 도구를 사용해 보려는 사람들이 마찰점이나 누락된 기능을 발견했을 때 나오는 것입니다. 실제 작업에 도구를 사용할 때 겪을 수 있는 어려움을 이해하는 것은 우리에게 매우 유용합니다.

항상 만들고 싶었던 것을 떠올려보고, 실제로 만들어 보세요. 만약 그 프로젝트를 완성할 수 있다면, 축하합니다! 이제 당신이 항상 원했던 것을 손에 넣은 것입니다.

그러나 성공하지 못하셨다면, 무엇이 문제였는지 알려주세요. 누락된 기능이 있었나요? 문서가 혼란스럽거나 부족한 부분이 있었나요? 여러분의 경험을 공유해 주시면 저희가 계획 수립 과정을 개선하는 데 유용한 통찰력을 얻을 수 있습니다.

문제가 발생할 경우, 새로운 토론 주제를 시작해 주세요. 이는 새로운 이슈나 기능 제안의 시작점이 될 수 있습니다.

기여 도구 사용¶

새 이슈 제출

잘 작성된 문제 또는 버그 보고서는 문제 해결 능력에 큰 차이를 만들 수 있습니다. 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>

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

새로운 기능 제안

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

조사해 보세요¶

첫 번째 단계는 BeeWare 이슈 트래커에서 기존 기능 관련 이슈(‘enhancement’ 태그가 지정된 이슈), 문서 관련 이슈(‘documentation’ 태그가 지정된 이슈), 또는 토론 스레드를 검색하여 해당 아이디어가 이전에 제안된 적이 있는지 확인하는 것입니다. 이미 제안된 경우, 새로운 맥락이나 아이디어가 있다면 기존 스레드에 추가하세요. 조사에 도움이 필요하면 BeeWare Discord의 #dev 채널에서 문의할 수 있습니다. 기존 스레드를 안내하거나, 여러분이 알지 못할 수 있는 맥락을 제공하거나, 당장 관련이 없어 보이는 다른 아이디어와 여러분의 아이디어를 연결해 드릴 수 있습니다.

아이디어를 논의하다¶

기존에 해당 아이디어에 대한 언급을 찾지 못하셨다면, 토론 스레드를 시작하세요. 아이디어의 목적과 사용 사례에 대한 개요를 제공하십시오. 구현 시 기능의 형태(예: API의 일반적인 구조, 기능의 시각적 외관, 추가될 문서 등)에 대한 생각도 포함시키세요. 해당되는 경우, 아이디어가 다양한 플랫폼에서 어떻게 구현될지에 대한 연구 결과도 포함해야 합니다.

토론 스레드가 개설되면 BeeWare 팀과 커뮤니티 구성원들이 답변을 드릴 것입니다. 핵심 팀은 귀하의 아이디어에 대해 최소한 초기 의견을 업무일 기준 2일 이내에 제공하기 위해 노력할 것입니다. 아이디어가 특히 복잡한 경우, 보다 상세한 분석에는 최대 일주일이 소요될 수 있습니다. 휴일이나 컨퍼런스 같은 행사로 인해 해당 일정이 다소 지연될 수 있습니다.

여러분의 아이디어에 대한 대화에 참여할 수 있는 기회입니다. 저희가 추가적인 세부사항이나 배경 정보를 요청할 수 있습니다. 커뮤니티의 다른 구성원들도 토론에 참여하여 다른 관점, 제안 또는 대안을 제시할 수 있습니다. 이 논의의 결과가 향후 진행 방향을 결정하게 됩니다.

모든 아이디어가 받아들여지는 것은 아니라는 점을 이해하는 것이 중요합니다. 이 과정이 제안서 제출로 시작되는 이유는, 여러분이 모든 작업을 마친 후에야 변경 사항이 받아들여지지 않는 이유가 있다는 사실을 알게 되는 상황을 피하기 위함입니다.

그렇다고 해서 좋은 아이디어가 아니었다는 뜻은 아닙니다! 기술적인 이유로 구현이 불가능할 수도 있습니다. 예를 들어, 다음과 같은 경우에는 아이디어를 거부할 수 있습니다:

모든 지원 플랫폼에서 안정적으로 구현하기 어렵거나 불가능할 수 있습니다; 또는
유지 관리가 어려울 수 있거나, 유지 관리를 위해서는 널리 보급되지 않은 기술이나 소프트웨어에 대한 접근이 필요할 수 있습니다; 또는
특정 사용자층을 대상으로 하지만, 다른 사용자에게 상당한 부담을 가중시킵니다.

만약 귀하의 아이디어가 적합하지 않다고 판단되더라도, 반드시 포기해야 한다는 의미는 아닙니다. 특정 아이디어를 거절할 수는 있지만, 플러그인 인터페이스나 기타 확장 지점을 추가하여 동일한 기능을 외부 라이브러리로 유지할 수 있도록 하는 방안에는 훨씬 더 개방적일 수 있습니다. 이렇게 하면 해당 기능을 유지하면서도, 기능 자체의 유지보수 문제나 제약이 프로젝트에 부담이 되는 상황을 피할 수 있습니다.

공식 기능 요청으로 전환¶

특징의 형태에 대한 논의가 합의에 도달하면, beeware 이슈 트래커에서 논의 내용을 요약하고 맥락을 위해 해당 논의로 연결되는 링크를 포함하는 새로운 기능 요청 이슈를 생성할 수 있습니다.

기능 제안 사항을 직접 구현할 필요는 없습니다. 제안 내용의 세부 사항을 담은 이슈를 생성하면 됩니다. 다만, 단순히 이슈를 게시한다고 해서 해당 기능이 반드시 구현되는 것은 아닙니다. 동일한 기능에 관심 있는 다른 커뮤니티 구성원이나 핵심 팀원이 이를 채택할 가능성을 기다려야 합니다. 다만 이는 보장되지 않습니다. 확실한 구현을 원한다면 직접 구현하거나, 다른 사람에게 구현을 의뢰해야 합니다.