문제 해결¶

BeeWare는 알려진 문제점 목록을 추적합니다. 이 문제점들은 모두 작업 대상 후보입니다.

이 목록은 다양한 방식으로 필터링할 수 있습니다. 예를 들어 플랫폼별로 필터링하여 테스트 가능한 플랫폼에 영향을 미치는 이슈에 집중하거나, 문서 버그과 같은 이슈 유형별로 필터링할 수 있습니다. 초보자에게 적합한 이슈 필터도 있습니다. 이는 원인이 알려진 문제로 식별된 이슈들로, 수정 방법이 비교적 간단할 것으로 예상됩니다(분석이 틀릴 수도 있지만).

이슈가 6개월 이상 경과한 경우, 해당 문제가 이미 해결되었을 가능성이 높습니다. 따라서 첫 번째 단계는 문제를 재현할 수 있는지 확인하는 것입니다. 버그 보고서에 제공된 정보를 활용하여 문제를 재현해 보십시오. 문제를 재현할 수 없다면, 발견한 내용을 해당 이슈에 댓글로 보고하고 다른 이슈를 선택하십시오.

문제를 재현할 수 있다면 직접 해결해 보세요! 해당 기능을 구현하는 코드 조합을 파악하고, 어떤 부분이 제대로 작동하지 않는지 분석해 보십시오.

문제를 해결하지 못하더라도, 해결 과정에서 발견한 내용을 이슈에 대한 코멘트로 보고하는 것만으로도 가치가 있습니다. 문제의 원인은 찾았지만 해결책은 찾지 못했다 해도, 그 지식만으로도 해당 플랫폼에 더 정통한 사람이 문제를 해결하는 데 충분할 때가 많습니다. 이슈에 이미 재현 사례(문제를 재현하는 것 외에는 아무것도 하지 않는 작은 샘플 앱)가 제공되지 않았다면, 이를 제공하는 것이 큰 도움이 될 수 있습니다.

이슈 수정 기여¶

개발 환경 설정

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

선행 조건¶

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

macOSLinuxWindows

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

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

$ python3 --version

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

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

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

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

$ python3 --version

여러 버전의 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로 저장소를 컴퓨터에 복제하세요:

macOSLinuxWindows

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

$ git clone https://github.com/<your username>/beeware.git

(GitHub 사용자 이름을 대체)

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

$ git clone https://github.com/<your username>/beeware.git

(GitHub 사용자 이름을 대체)

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

C:\...>git clone https://github.com/<your username>/beeware.git

(GitHub 사용자 이름을 대체)

가상 환경 생성¶

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

macOSLinuxWindows

$ 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할 수 있습니다. 다음 명령어를 실행하세요:

macOSLinuxWindows

(.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을 활성화하려면 다음 명령을 실행하세요:

macOSLinuxWindows

(.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 기능 브랜치를 생성하려면 다음을 실행하세요:

macOSLinuxWindows

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

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

(.venv) C:\...>git switch -c fix-win11-build

문제를 재현하십시오

문제가 존재하지 않는다면 해결할 수도 없습니다. 따라서 문제를 재현하는 것은 해결의 전제 조건입니다. 소프트웨어 분야에서 문제는 일반적으로 "버그"이라 불리며, 이슈는 흔히 "버그 리포트"라고 합니다.

누군가 버그 보고서를 제출했습니다. 보고자가 설명한 단계가 실제로 보고된 버그를 발생시키는지 확인해야 합니다. 보고서에 정확히 기술된 대로 수행했을 때 동일한 결과를 재현할 수 있습니까? 재현할 수 없다면 그 이유를 파악해야 합니다.

코드 내 버그¶

이상적인 상황에서는 버그를 보고한 사람과 동일한 환경을 갖추고, 해당 단계를 따라가며, 설명된 대로 버그를 재현할 수 있을 것입니다. 하지만 대부분의 경우 그렇게 간단하지 않습니다. 많은 버그 보고서는 모호한 설명과 불분명한 조건만 포함합니다. 문제는 많은 버그가 관련된 조건 집합에 따라 달라진다는 점입니다. 여기에는 상호작용 방식, 다양한 전제 조건, 운영 체제, 운영 체제 버전, CPU 아키텍처, 사용자의 컴퓨터가 오래되고 느린지 새롭고 빠른지 등이 포함됩니다. 버그를 둘러싼 상황에 대한 정보가 많을수록 좋습니다. 보고자가 제시한 조건 집합을 재현해 보십시오. 재현이 불가능하다면, 다음 단계로 버그를 보고한 사람에게 추가 정보를 요청해야 할 수 있습니다.

버그를 재현하는 가장 좋은 방법은 문제를 여전히 보여주는 최소한의 예제를 사용하는 것입니다. 대부분의 경우 보고자들은 최소한의 실행 가능한 예제를 제공하지 않습니다. 만약 그들이 어떤 예제를 제공하더라도, 그것은 그들의 "실제 환경" 애플리케이션에서 직접 복사한 것일 것입니다. 보고서를 문제 현상이 나타나는 가장 단순한 형태로 축소하는 것이 목표입니다. 재현 사례는 가능한 한 최소한의 프로그램이어야 합니다. 이러한 축소 과정 자체가 실제 문제점을 규명하는 데 도움이 됩니다. 누구나 최소한의 예제를 가져와 실행하면 보고된 버그를 관찰할 수 있습니다.

문서상의 오류¶

문서상의 버그는 다양한 형태로 나타날 수 있습니다. 서식 문제로 인해 렌더링 오류가 발생할 수 있습니다. 때로는 버그가 아닌 경우도 있습니다. 작성자가 문서를 잘못 읽었거나 단순한 실수를 했을 수 있습니다. 그렇다고 해서 문서 자체에 문제가 없다는 뜻은 아닙니다. 내용이 불명확하거나 부정확하여 혼란이나 오해의 여지를 남길 수 있습니다. 설명되어야 할 개념이 문서화되지 않아 누락된 경우도 있습니다.

문서화 문제에 대한 버그가 등록되면, 보고된 문제가 실제로 여전히 존재하는지 확인해야 합니다. 렌더링 문제의 경우, 문서를 빌드하여 문제를 재현할 수 있는지 확인해야 합니다. 콘텐츠 문제는 아무도 업데이트를 제출하지 않았는지 확인하기 위해 읽어보는 문제입니다.

이슈 업데이트¶

트라이아지 프로세스의 마지막 단계는 이슈에 코멘트를 남김으로써 발견 사항을 문서화하는 것입니다.

문제를 정확히 재현할 수 있다면, 그 사실만 전달하시면 됩니다. 원본 보고자가 설명한 방식과 정확히 동일하게 동일한 문제가 발생함을 확인했다는 내용의 댓글을 남겨주세요.

추가적인 맥락을 제공할 수 있다면 해당 맥락에 대한 세부 사항을 포함하십시오. 여기에는 다른 운영 체제에서 문제를 재현할 수 있는지, 관련 소프트웨어의 다른 버전에서 재현 가능한지, 또는 원래 보고와 다른 모든 사항이 포함될 수 있습니다.

원본 보고서에 재현에 필요한 세부 사항이 누락된 경우, 해당 세부 사항을 포함하십시오. 여기에는 원본 보고서에 명시되지 않은 운영 체제 또는 버전 정보, 보다 완전한 로그나 스택 추적 정보, 문제 재현에 필요한 정확한 작업 순서에 대한 명확한 지침 등이 포함될 수 있습니다. 문제를 재현하는 더 간단한 방법을 개발한 경우(또는 원본 보고자가 재현 사례를 제공하지 않은 경우), 해당 재현 방법론에 대한 세부 사항을 포함할 수 있습니다.

문제를 재현할 수 없다면, 시도한 내용을 상세히 기술하여 댓글을 남겨주세요. 문제가 존재하지 않는 곳을 아는 것은 문제가 존재하는 곳을 아는 것만큼 중요합니다. 이는 가능한 원인을 좁히는 데 도움이 되기 때문입니다. 문제를 재현할 수 없는 이유에 대한 가설이 있다면(예: 사용법 오류라고 생각하거나 최근 운영체제 업데이트로 해결되었다고 판단하는 경우) 해당 추측도 댓글에 포함해 주세요.

마지막으로, 핵심 팀에 제안할 사항이 있다면 알려주시기 바랍니다. 원본 보고서에 오류가 있다고 생각되면 해당 이슈를 종료할 것을 제안하시고, 이슈의 원인에 대한 가설이 있다면 그 역시 제안하실 수 있습니다. 여러분의 의견은 핵심 팀이 해당 이슈를 다음 단계로 진행하는 방법을 모색하는 데 도움이 될 것입니다.

문제를 해결하기 위해 코드 변경이 필요한 경우:

코드를 작성하고, 실행하고, 테스트합니다.

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

macOSLinuxWindows

(.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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
총계 7540 0 1040 0 100.0%

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

이름 명세서 분실 지점 지점 부분 커버 미포함
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
총계 7540 1 1726 0 99.9%

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

문서 수정이 필요한 경우:

/// details-abstract | 문서 작성

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



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

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

### 라이브 문서 미리보기

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

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

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

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

///

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



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(venv) $ tox -e docs-live

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

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

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

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

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

docs-live는 초기 단계입니다

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

로컬 빌드¶

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

로컬 빌드 생성¶

로컬 빌드를 생성하려면:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

로컬 번역 빌드 생성¶

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

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

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

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

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

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

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

문서 린팅¶

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

macOSLinuxWindows

(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에서 아무것도 변경할 필요가 없습니다. 예를 들어:

- ./path/to/directory/*

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

- [My new document](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 검사로 코드 포맷팅 문제가 발견되었습니다:

macOSLinuxWindows

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

macOSLinuxWindows

(.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이 강조 표시되어 있습니다.

macOSLinuxWindows

(.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를 통과하거나, 통과하지 못한 이유에 대한 설명을 제공할 때까지 완료되지 않습니다.