콘텐츠로 이동

문서 추가

세계 최고의 소프트웨어를 가지고 있을지라도, 아무도 사용법을 모른다면 무슨 소용이 있겠습니까? 문서는 항상 개선될 수 있습니다. 여러분의 도움이 필요합니다!

문서 양식

BeeWare's 문서화는 MkDocs와 Markdown을 사용하여 작성됩니다. 우리는 문서 구조화를 위해 Diataxis 프레임워크를 따르도록 노력합니다.

디아택시스 프레임워크는 문서화의 네 가지 "형태"를 설명합니다:

  • 튜토리얼 - 특정 프로젝트 완성을 목표로 하는 안내형 학습 경험.
  • 방법 안내서 - 독자를 특정 목표나 결과로 이끄는 지침.
  • 주제 안내 - 단일 아이디어에 대한 논의로, 그 밑바탕이 되는 개념들이 명확히 설명되도록 구성됨.
  • 참고 - 특정 API 또는 기타 인터페이스에 대한 기술적 설명.

문서 작업에 착수하기 전에 어떤 형식이 가장 적합한지 파악하는 것이 중요합니다. 많은 문서 제안은 처음에 "X에 관한 튜토리얼" 요청으로 설명되지만, 대부분의 경우 실제로 필요한 것은 사용 방법, 주제별 가이드 또는 개선된 참조 정보입니다.

예를 들어, 쿠키 굽기에 관한 설명서를 작성하는 작업을 생각해 보자.

튜토리얼

튜토리얼은 특히 초보자를 대상으로 한 입문서로, 독자를 백지 상태에서 완성된 결과물까지 이끄는 것을 목표로 합니다. 이를 위해서는 매우 구체적인 지침과 각 단계를 맥락에 맞게 설명하는 상세한 해설이 필요합니다. 설명 대상 도구에 대한 독자의 경험은 전혀 가정하지 않아야 하지만, 기본적인 파이썬 숙련도는 어느 정도 있다고 가정하는 것이 합리적입니다.

튜토리얼에는 독자가 설명된 작업을 성공적으로 수행했는지 확인할 수 있는 정기적인 점검 지점이 포함되어야 합니다. 각 점검 지점에서 성공 기준은 명확해야 합니다. 독자가 경험할 수 있는 예상 오류나 문제에 대한 설명을 포함하여 알려진 실패 사례를 명확히 기술해야 합니다. 독자의 작업으로 인해 변경되는 사항은 명백해 보이더라도 반드시 지적해야 합니다. 반복 설명은 권장됩니다. 특히 모범 사례나 공통 프로세스를 정립하려는 경우 더욱 그렇습니다. 내부 구조에 대한 설명은 피해야 하며, 동일한 결과에 도달하는 대체 경로 역시 언급하지 않아야 합니다.

쿠키 굽는 법에 관한 튜토리얼은 단순한 레시피 그 이상입니다. 튜토리얼의 설명은 한 번도 베이킹을 해본 적 없는 사람(예: 어린이)도 이해할 수 있어야 하며, 설탕과 버터를 크림화하는 방법, 오븐 예열 과정, 먹기 전에 쿠키를 얼마나 오래 식혀야 하는지 등 경험 많은 베이커가 당연하게 여기는 사항들도 설명해야 합니다. 이 튜토리얼의 목표는 단순히 쿠키를 만드는 것이 아니라 베이킹의 기본 원리를 전달하는 데 있습니다. 완성된 쿠키는 누군가 처음부터 이 튜토리얼을 시작하게 만드는 맛있는 결과물일 뿐입니다.

방법 안내서

실용 가이드(how-to guide)는 이론적 설명보다는 특정 실제 사용 사례와 실질적인 결과에 초점을 맞춰야 합니다. 튜토리얼과 달리 기존 도구에 대한 어느 정도의 이해도를 가정할 수 있습니다. 독자는 가이드를 처음부터 끝까지 따라가 목표에 도달할 수 있어야 하지만, 이를 위해 기존 지식이 필요할 수 있습니다. 가이드의 목표를 달성하기 위해 따라야 할 구체적인 지침이나 논리적인 단계들을 포함해야 합니다.

요리책에 실린 레시피는 방법 안내서의 좋은 예시입니다. 초콜릿 칩 쿠키 레시피는 다양하지만 모두 공통된 특징을 공유합니다. 그러나 특정 레시피는 처음부터 끝까지 따라할 수 있어야 하며 일관된 결과를 내야 합니다. 훌륭한 초콜릿 칩 쿠키 레시피는 설탕이나 밀가루 종류의 상대적 장점에 대해 논하거나 기본적인 기술이나 과정에 대한 상세한 설명을 제공하지 않습니다. 독자가 베이킹에 대한 기본적인 지식을 갖추고 있다고 가정하고, 쿠키 한 판을 굽는 데 필요한 재료와 조리법만을 포함합니다.

주제 안내서

주제 가이드는 단일 주제나 아이디어를 설명합니다. 예제 코드나 지침을 포함할 수 있지만, 전반적인 개념에 대한 고수준의 개요를 제공하는 데 훨씬 더 중점을 둡니다. 의견이나 대체 관점을 포함할 수 있으나, 가이드의 특정 주제에 대한 초점은 유지되어야 합니다.

쿠키 굽기에 관한 주제 안내서는 쿠키라는 제과 제품의 역사에 대해 다루거나, 산업화된 공정으로 만들어진 쿠키와 집에서 만든 쿠키의 차이점을 탐구하거나, 균형 잡힌 식단에 쿠키를 포함시키는 방법을 제안할 수 있습니다. 이 안내서 자체만으로는 쿠키를 굽고자 할 때 따라하기에 그다지 유용한 문서는 아니지만, 제빵에 익숙한 사람이 기존 쿠키 레시피를 성공적으로 변형하는 데 필요한 배경 지식을 제공할 수 있습니다.

참고

참조 문서는 정보 중심적이며, 도구 라이브러리의 작동 세부 사항을 설명합니다. 코드 자체에서 생성될 수 있지만, 우수한 API 문서는 추가 설명과 맥락이 필요할 수 있습니다. 사용 예시가 포함될 수 있으나, 상세한 설명은 피해야 합니다.

베이킹 참고서에는 사용 가능한 설탕 종류와 베이킹 시 그 특성에 대한 상세한 설명이 수록될 수 있습니다. 이는 설탕에 관한 문자 그대로의 사실을 기술하지만, 설탕 종류 선택에 관한 포괄적인 논의는 방법 안내서나 주제별 가이드의 주제가 되어야 합니다. 대부분의 포장 식품에 표시된 영양 정보는 참고 자료로 간주됩니다.

문서화 스타일

BeeWare's 문서화는 문서 스타일 가이드에 명시된 지침을 따릅니다. 이 가이드에는 기본 스타일과 서식, 맞춤법 검사 절차가 포함됩니다. 또한 참조 링크 구문, 코드 블록 작업 팁, 이미지 처리 등 다양한 마크다운 구문 세부 사항도 다룹니다.

기여 문서

새로운 문서 제안

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

조사해 보세요

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

아이디어를 논의하다

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

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

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

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

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

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

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

공식 기능 요청으로 전환

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

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

개발 환경 설정

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

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

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

건축 문서

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

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

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

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