콘텐츠로 이동

새로운 기능 구현

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

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

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

새로운 기능 기여

개발 환경 설정

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

선행 조건

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

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

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를 업그레이드하려면 다음을 실행하십시오:

$ 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)로 이어질 수 있는지 고려해야 합니다. 두 가지 별개의 기능을 분리하여 구현할 수 있는가? 알려진 제한사항이나 버그를 감수하고 기능을 구현한 후, 후속 풀 리퀘스트에서 해당 버그를 수정할 수 있는가? 버그 수정 작업의 일부가 다른 부분과 독립적으로 수행될 수 있는가? 변경 사항의 일부를 제외해도 원래 기여물에 영향을 미치지 않는다면, 그 부분은 제외하는 것이 바람직하다.

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

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

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

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:

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

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

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

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

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

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

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

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

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

로컬 빌드

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

로컬 빌드 생성

로컬 빌드를 생성하려면:

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

로컬 번역 빌드 생성

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

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

(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>를 실행하여 해당 개별 빌드를 따로 실행할 수 있습니다. 예를 들어, 프랑스어 문서만 빌드하려면 다음을 실행하세요:

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

- ./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 검사로 코드 포맷팅 문제가 발견되었습니다:

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