PEP 676 – PEP 인프라 프로세스

Author:: Adam Turner <adam at python.org>
Sponsor:: Mariatta <mariatta at python.org>
PEP-Delegate:: Barry Warsaw <barry at python.org>
Discussions-To:: Discourse thread
Status:: Active
Type:: Process
Created:: 01-Nov-2021
Post-History:: 23-Sep-2021, 30-Nov-2021
Resolution:: Discourse message

Table of Contents

초록
동기
근거
- 인프라의 단순화와 중앙 집중화
- 사용성 개선과 이슈 해결
명세
하위 호환성
보안 영향
교육 방법
참조 구현
기각된 아이디어
감사의 글
각주
Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

초록

이 PEP는 PEP 파일을 reStructuredText 파일에서 HTML 웹 페이지로 렌더링하는 작업을 둘러싼 인프라를 다룹니다. 우리는 PEP 독자, 저자, 편집자를 위해 자체적으로 완결되고 유지 보수하기 쉬운 해결책을 명세하고자 합니다.

2021년 11월 현재, Python 개선 제안(PEP)은 여러 시스템에 걸친 다단계 프로세스로 렌더링됩니다. 지속적 통합(CI) 작업이 docutils 스크립트를 실행하여 모든 PEP 파일을 개별적으로 렌더링합니다. 그다음 CI 작업이 tar 아카이브를 서버에 업로드하면, 그 서버에서 아카이브를 주기적으로 가져와 python.org 웹사이트에 렌더링합니다.

이 때문에 python.org 웹사이트가 원시 HTML 업로드와 PEP 렌더링을 처리해야 한다는 제약이 생기며, 경우에 따라서는 이슈를 제기할 적절한 곳이 불분명해집니다 [1].

이 PEP는 PEP를 자체적으로 완결된 방식으로 렌더링하기 위한 명세를 제공합니다. 이를 통해 다음과 같은 일이 가능해집니다:

PEP 지원에 필요한 분산된 구성의 양을 줄입니다
PEP를 읽고, 쓰고, 검토하는 사람들을 위한 사용성 개선을 가능하게 합니다
여러 미해결 이슈를 해결하고, 앞으로의 개선을 위한 길을 닦습니다
자원봉사 유지 관리자의 시간을 절약합니다

우리는 PEP에 최상위 경로의 peps.python.org를 통해 접근하고(예: peps.python.org/pep-0008), PEP 렌더링을 지원하는 모든 맞춤 도구를 python/peps 저장소에서 호스팅할 것을 제안합니다.

근거

인프라의 단순화와 중앙 집중화

2021년 11월 현재, PEP 파일을 로컬에서 렌더링하려면 PEP 작성자나 편집자는 python.org 웹사이트의 전체 로컬 인스턴스를 만들고, python/peps 저장소 바깥에 있는 documentation을 따라 서로 다른 여러 스크립트를 실행해야 합니다.

반면 제안된 구현은 모든 PEP 파일을 렌더링하는 하나의 Makefile과 Python 스크립트를 제공하며, 웹 서버나 로컬 파일 시스템을 대상으로 하는 옵션을 갖추고 있습니다.

모든 도구를 단일 저장소에서 호스팅하면 이슈를 제기할 곳이 명확해져, 자원봉사자가 이슈 분류에 들이는 시간이 줄어듭니다.

또한 PEP 렌더링 인프라의 범위가 명확하게 정의되어 있으므로, 단순화되고 중앙 집중화된 도구는 추가 개선에 참여하는 진입 장벽을 낮출 수도 있습니다.

사용성 개선과 이슈 해결

PEP를 읽을 때 쓸 추가 기능에 대한 요청이 여럿 있으며, 예를 들면 다음과 같습니다:

문법 강조 [2]
.. code-block:: 지시문 사용 [2]
SVG 이미지 지원 [3]
타이포그래피 따옴표 [4]
추가 바닥글 정보 [5]
intersphinx 기능 [6]
다크 모드 테마 [7]

이것들은 이 제안으로 얻을 수 있는 “손쉬운 성과”이며, PEP를 이용하는 사람들(검토자와 저자 포함)의 사용성을 높이는 데 도움이 될 것입니다.

예를 들어, 현재(2021년 11월 기준) 시스템은 일정에 따라 주기적으로 실행됩니다. 이 때문에 PEP의 변경 사항을 즉시 배포할 수 없어 생산성이 떨어집니다. 참조 구현은 저장소에 커밋이 있을 때마다 모든 PEP를 렌더링하고 게시하므로, 설계상 이 문제를 해결합니다.

참조 구현은 여러 문제를 해결합니다 [8]. 예를 들면 다음과 같습니다:

현재 python.org의 스타일시트는 목록 스타일을 반영하지 않습니다
python.org에서는 PEP의 이미지를 갱신하기가 어렵습니다

Read the Docs나 Netlify 같은 서드파티 제공자는 풀 리퀘스트 자동 렌더링 같은 기능으로 이 경험을 향상할 수 있습니다.

명세

PEP 파일을 HTML로 렌더링하기 위해 제안하는 명세는 Reference Implementation을 따릅니다.

렌더링된 PEP는 반드시(MUST) peps.python.org에서 제공되어야 합니다. 이들은 정적 파일로 호스팅되어야 하며(SHOULD), 콘텐츠 전송 네트워크(CDN) 뒤에 둘 수 있습니다(MAY).

풀 리퀘스트의 미리 보기를 렌더링하는 서비스를 제공해야 합니다(SHOULD). 이 서비스는 호스팅 및 배포 솔루션과 통합될 수 있습니다(MAY).

python.org 도메인에 다음 리디렉션 규칙을 반드시(MUST) 만들어야 합니다:

/peps/ -> https://peps.python.org/
/dev/peps/ -> https://peps.python.org/
/peps/(.*)\.html -> https://peps.python.org/$1
/dev/peps/(.*) -> https://peps.python.org/$1

다음 nginx 설정으로 이를 구현할 수 있습니다:

location ~ ^/dev/peps/?(.*)$ {
    return 308 https://peps.python.org/$1/;
}

location ~ ^/peps/(.*)\.html$ {
    return 308 https://peps.python.org/$1/;
}

location ^/(dev/)?peps(/.*)?$ {
    return 308 https://peps.python.org/;
}

리디렉션은 하위 호환성을 위해 반드시(MUST) URL fragments를 보존하도록 구현해야 합니다.

Hugo van Kemenade
Pablo Galindo Salgado
Éric Araujo
Mariatta
C.A.M. Gerlach

각주

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.