Flower Enhancement Doc¶
목차¶
목차
요약
동기
목표
비목표
제안
Enhancement Doc 템플릿
워크플로우
단점
[고려되는 대안](#고려되는 대안)
요약¶
Flower Enhancement는 다음과 같은 표준화된 개발 프로세스입니다
더 큰 변경 사항을 제안하기 위한 공통 구조를 제공합니다
변화의 동기가 분명한지 확인합니다
버전 관리 시스템에서 프로젝트 정보를 유지합니다
사용자에게 영향력 있는 변화에 대한 동기를 문서화합니다
운행 중 작업 추적을 위한 깃허브 이슈를 예약합니다
커뮤니티 참여자가 하나 이상의 릴리즈에서 변경 사항을 성공적으로 완료할 수 있도록 하는 동시에 이해 관계자가 프로세스 전반에 걸쳐 적절히 대표되도록 보장합니다
따라서 Enhancement 문서에는 다음과 같은 측면이 결합되어 있습니다
기능 및 effort-tracking 문서
제품 요구 사항 문서
디자인 문서
를 하나의 파일로 통합하여 커뮤니티와 협력해 점진적으로 생성합니다.
동기¶
Flower에 제안된 변경 사항이나 기능을 멀리 가져오는 경우, 프로젝트의 향후 변경 사항을 이해하고 전달하기 위해 단일 GitHub 이슈 또는 pull request를 넘어서는 abstraction이 필요합니다.
이 프로세스의 목적은 커뮤니티 내 ‘부족한 지식’의 양을 줄이는 것입니다. 이 프로세스는 Slack 스레드, 영상 통화, 복도 대화에서 나온 의사 결정을 잘 추적된 아티팩트로 옮김으로써 커뮤니케이션과 검색 가능성을 향상시키는 것을 목표로 합니다.
목표¶
대략적으로 사용자를 대상으로 하는 대규모 개선 사항은 개선 프로세스를 따라야 합니다. 개선 사항을 작성자나 개발자 이외의 다른 사람에게 서면 또는 구두로 설명해야 하는 경우에는 개선 문서 작성을 고려하세요.
마찬가지로 개발 커뮤니티의 많은 부분에 영향을 미치는 기술적 노력(리팩토링, 주요 아키텍처 변경)도 널리 알려야 합니다. 개선 프로세스는 일반 사용자나 운영자에게 전혀 영향을 미치지 않더라도 이를 위해 적합합니다.
목표가 아닌 것¶
작은 변경 및 추가의 경우, 개선 프로세스를 거치는 것은 시간이 많이 걸리고 불필요합니다. 예를 들어, 새로운 연합 학습 알고리즘을 추가하는 것은 Flower의 작동 방식이나 사용 방식을 변경하지 않고 기능만 추가하는 것이기 때문입니다.
기능 개선은 이미 구현할 수 있는 경로가 마련되어 있고 커뮤니티 구성원들이 지지하는 것이므로 기능 요청과는 다릅니다.
제안¶
개선 사항은 정의된 템플릿과 참조용으로 Enhancement Doc.를 검토하고 저장하는 워크플로우를 따르는 Markdown 파일에 캡처됩니다.
Enhancement Doc 템플릿¶
각 개선 사항 문서는 다음과 같은 구조의 Markdown 파일로 제공됩니다
Metadata (아래 설명 YAML preamble 형식)
Title (metadata와 같게)
Table of Contents (필요시)
요약
동기
목표
목표가 아닌 것
제안
Notes/Constraints/Caveats (선택 사항)
Design Details (선택 사항)
졸업 기준
업그레이드/다운그레이드 전략(해당되는 경우)
단점
고려되는 대안
참고로 이 문서는 위의 구조를 따릅니다.
Metadata¶
피드 번호 (필수) 마지막 Flower Enhancement 문서의
피드 번호+ 1. 이 번호를 사용하면 다른 제안을 쉽게 참조할 수 있습니다.제목 (필수) 제안서의 제목을 평이한 언어로 입력합니다.
상태 (필수) 제안의 현재 상태입니다. 가능한 상태는 워크플로를 참조하세요.
저자 (필수) 제안서의 작성자 목록입니다. 간단히 GitHub ID입니다.
생성 날짜 (필수) PR에서 제안서를 처음 제출한 날짜입니다.
마지막 업데이트 (선택 사항) 제안서가 마지막으로 크게 변경된 날짜입니다.
함께 보기 (선택 사항) 이 제안과 관련된 다른 제안 목록입니다.
대체 (선택 사항) 이 제안이 대체하는 제안 목록입니다.
대체됨 (선택 사항) 이 제안이 대체하는 제안의 목록입니다.
워크플로우¶
개선 사항을 구성하는 아이디어는 이미 커뮤니티에서 논의되었거나 제안된 적이 있어야 합니다. 따라서 개선 사항을 주도하는 사(보통 작성자)이 필요합니다. 이 사람은 또한 제안을 검토할 의향이 있는 Flower 커미터를 찾아야 합니다.
새 개선 사항은 NNNN-YYYYMMDD-enhancement-title.md 형식의 파일 이름으로 체크인되며, NNNN은 Flower 개선 문서 번호이고 enhancements에 해당합니다. 모든 개선 사항은 pull request의 일부로 잠정 상태에서 시작됩니다. 토론은 pull request 검토의 일부로 이루어집니다.
개선 사항이 검토 및 승인되면 상태가 ‘구현 가능’으로 변경됩니다. 그런 다음 실제 구현은 별도의 pull requests를 통해 이루어집니다. 이러한 pull requests는 설명의 일부로 해당 개선 사항을 언급해야 합니다. 구현이 완료되면 제안 상태는 ‘구현됨’으로 변경됩니다.
특정 조건에서는 다른 상태도 가능합니다. 개선에는 다음과 같은 상태가 있습니다:
‘잠정적’: 개선 사항이 제안되어 활발히 정의되고 있습니다. 제안이 구체화되고 활발하게 정의 및 논의되는 동안의 시작 단계입니다.
구현 가능: 개선 사항이 검토 및 승인되었습니다.구현됨: 개선 사항이 구현되었으며 더 이상 활발히 변경되지 않습니다.‘지연됨’: 개선 사항이 제안되었지만 아직 활발히 작업 중이 아닙니다.
거부됨: 작성자와 검토자는 이 개선 사항을 더 이상 진행하지 않기로 결정했습니다.철회: 작성자가 개선 사항을 철회했습니다.‘대체됨’: 개선 사항이 새로운 개선 사항으로 대체되었습니다.
단점¶
GitHub에서 이미 제공하는 프로세스(이슈 및 Pull Requests)에 추가 프로세스를 추가하면 더 복잡해지고 잠재적인 처음인 기여자에게는 장벽이 될 수 있습니다.
현재 기능 이슈 템플릿에서 요구되는 한 문장 설명 이상으로 제안서 템플릿을 확장하는 것은 영어가 모국어가 아닌 사용자에게는 큰 부담이 될 수 있습니다.
고려되는 대안¶
GitHub 이슈¶
이러한 종류의 개선을 위해 GitHub 이슈를 사용하면 가능합니다. 예를 들어 태그를 사용하여 다른 이슈와 구별하고 필터링할 수 있습니다. 주요 이슈는 개선 사항에 대해 토론하고 검토하는 것입니다: GitHub 이슈에는 댓글 스레드가 하나만 있습니다. 개선 사항에는 일반적으로 문서의 여러 부분에 대해 동시에 여러 개의 토론 스레드가 있습니다. GitHub 이슈를 사용할 때 이러한 여러 토론을 관리하면 혼란스러울 수 있습니다.
Google 문서 도구¶
Google 문서는 여러 스레드의 토론을 허용합니다. 하지만 Google 문서는 프로젝트 외부에서 호스팅되므로 커뮤니티에서 검색할 수 있도록 관리해야 합니다. 모든 제안에 대한 링크 목록을 관리하고 커뮤니티에 제공해야 합니다. Flower 저장소의 일부로 제안서를 보낼 때와 비교하면 링크가 누락될 가능성이 훨씬 더 높습니다.