다운스트림 포크 유지 관리
개요
다운스트림 포크를 유지하는 목적은 점차 업스트림에서 멀어져 독립적으로 진화하는 하드 포크가 되는 것이 아닙니다. PR이 아직 병합되지 않았거나, 업스트림 관리자가 바쁘거나, 패치가 틈새 시장이지만 긴급한 경우에도 사용자에게 이러한 기능과 수정 사항이 포함된 코드와 아티팩트를 신속하게 제공하면서 업스트림을 따라가는 것입니다. 정적인 패치 아카이브가 아니라 패치가 실제로 실행되고 검증되는 배포 채널입니다.
사용 가능한 통합 결과는 더 많은 사람들이 업스트림 PR, 다운스트림 패치 및 자신의 변경 사항을 자유롭게 테스트할 수 있게 해줍니다. 업스트림이 발전함에 따라 패치를 지속적으로 빌드, 테스트 및 검토하면 PR이 업스트림보다 뒤처져 부패할 위험을 줄이고, 문제를 조기에 발견하며, 변경 사항이 결국 업스트림으로 흘러갈 수 있도록 돕습니다.
핵심 목표
- 다운스트림 포크가 업스트림에서 분리된 하드 포크가 되는 것을 방지합니다.
- 단일 시점의 정적 브랜치만 보존하는 것이 아니라 지속적으로 업스트림을 따릅니다.
- 모든 패치를 독립적으로 빌드, 테스트, 검토 가능하게 유지하고 제출 또는 지속적인 PR 유지 관리에 적합하게 만듭니다.
- 메인 또는 릴리스 브랜치를 통해 직접 사용 가능한 코드와 아티팩트를 제공합니다.
- 사용자가 실제 통합 결과에 대해 PR, 패치 및 자신의 변경 사항을 테스트할 수 있도록 합니다.
- 패치와 업스트림 간의 충돌을 조기에 감지하고 PR을 병합 가능한 상태로 유지하며 패치가 업스트림으로 흘러갈 수 있도록 돕습니다.
브랜치 모델
저장소가 실제 브랜치 이름을 결정합니다. 기본 브랜치, 원격 이름 또는 호스팅 플랫폼을 가정하지 마십시오.
업스트림 메인 브랜치
업스트림 메인 브랜치는 모든 재구축의 시작점입니다. 동기화하기 전에 최신 상태를 가져오고, 현재 빌드의 기준선으로 특정 업스트림 커밋을 사용합니다.
다운스트림 메인 또는 릴리스 브랜치는 패치의 새로운 기준선이 되어서는 안 됩니다. 패치는 항상 업스트림을 기준으로 무엇을 변경하는지 명확히 해야 합니다.
패치 브랜치
각 독립 패치를 자체 브랜치에 유지하고 일반 PR 표준을 적용합니다:
- 범위를 집중하고 커밋과 설명을 명확하게 유지합니다.
- 동작을 입증할 수 있는 충분한 테스트를 포함합니다.
- 현재 업스트림에서 독립적으로 빌드 및 검토 가능하게 만듭니다.
- 필수 종속성만 선언하고 다른 다운스트림 패치에 연결하지 않습니다.
- 업스트림 PR로 직접 제출하거나 기존 PR을 계속 유지 관리하는 데 적합하게 만듭니다.
- 일반적으로 패치 브랜치는
CHANGELOG와 같이 업스트림 관리자가 중앙에서 관리하는 릴리스 파일을 수정해서는 안 됩니다. 필요한 문서 변경 사항은 해당 패치와 직접 관련된 코드 주석, API 문서 및 구현 노트로 제한되어야 합니다. 유지 관리 브랜치에서 중앙 집중식으로 다운스트림 패치 목록과 릴리스 노트를 유지 관리합니다.
패치 브랜치는 해당 패치의 장기적인 진실 공급원입니다. 릴리스 브랜치의 통합 커밋은 패치의 유일한 사본이 아니며 릴리스 기록에만 존재하는 임시 수정 사항을 포함해서는 안 됩니다.
임시 호환성 패치 브랜치
여러 패치가 독립적으로 적용되지만 결합될 때 개별 PR 브랜치에 속하지 않는 빌드, 테스트 또는 동작 충돌이 발생하는 경우 tmp/patch/<name> 브랜치에 호환성 패치를 유지 관리합니다.
이러한 브랜치는 특정 패치 조합에 대한 다운스트림 호환성 문제만 해결합니다. 독립 PR 브랜치 중 하나에 수정 사항을 강제로 넣지 말고, 새로운 장기 기능 브랜치가 되도록 두지 마십시오. 어떤 패치에 의존하는지, 순서상 어디에 속하는지, 어떤 결합 동작을 검증하는지, 언제 폐기될 수 있는지 명시해야 합니다.
ci 브랜치의 동기화 오케스트레이션에서 tmp/patch/<name>을 의존하는 패치 바로 다음 순서로 추가합니다. 이전 Git 병합에서 해결되지 않은 텍스트 충돌이 이미 발생한 경우 이후 호환성 브랜치는 해당 충돌을 넘을 수 없습니다. 이 경우 ci 오케스트레이션은 재구축을 계속하기 전에 충돌이 발생한 단계에서 해당 호환성 처리를 명시적으로 적용해야 합니다. 브랜치를 목록 끝에 추가하는 것만으로는 충분하지 않습니다.
ci 유지 관리 브랜치
포크가 GitHub Actions와 같은 자동화를 수행해야 하는 경우 별도의 ci 브랜치를 유지 관리합니다. 저장소에 이미 동등한 브랜치가 있으면 해당 이름을 유지합니다. 이 브랜치는 다운스트림 포크의 릴리스 오버레이이며 다음을 담당합니다:
- 다운스트림별 CI/CD, 패키징, 릴리스 및 저장소 구성.
- 업스트림 자동 가져오기, 패치를 순서대로 통합, 릴리스 브랜치 재구축 및 안전하게 푸시.
- 추가 다운스트림 단일 패치 테스트 및 다중 패치 통합 테스트.
- 다운스트림 README, 패치 목록, 릴리스 노트 및 다운스트림별 유지 관리 지침.
- 활성화된 일반 패치 및
tmp/patch/<name>브랜치의 고정 통합 순서.
사용자 또는 다운스트림 포크에 이 일반 워크플로를 넘어서는 유지 관리 요구 사항이 있는 경우 ci 브랜치의 다운스트림 소유 MAINTAIN.md에 보관합니다. 이 포크를 유지 관리하는 방법과 향후 유지 관리자 및 자동화가 따라야 할 특별 규칙을 명시해야 합니다. 저장소별 지침으로 취급하십시오. 패치 브랜치, 동기화 오케스트레이션 또는 릴리스 기록을 변경하기 전에 읽고, 해당 요구 사항이 변경될 때 최신 상태로 유지하십시오.
특별 유지 관리 규칙을 놓칠 수 있는 경우 ci 브랜치의 README.md에 MAINTAIN.md로 연결되는 간결한 알림을 추가합니다. 자세한 규칙은 README에 복제하지 말고 MAINTAIN.md에 보관합니다.
ci 브랜치는 중앙에서 다운스트림 릴리스 자동화를 수행할 수 있지만 제품 동작 패치를 혼합하지 마십시오. 런타임 변경 사항은 독립적인 빌드, 테스트 및 업스트림 PR 제출에 적합한 브랜치에 남아 있어야 합니다.
이 스킬에는 현재 관행에서 사용하는 GitHub Actions 파일인 ref/upstream-sync.yml이 포함되어 있습니다. GitHub 자동 동기화가 필요한 경우 .github/workflows/upstream-sync.yml의 시작점으로 복사한 다음 대상 저장소에 대해 업스트림 주소, 기본/릴리스 브랜치, ci 및 패치 목록, tmp/patch/<name> 순서, 동기화 일정, 다운스트림 소유 파일, 비밀 및 검사를 조정합니다. 이 파일은 원래 프로젝트의 프로젝트별 구성을 유지하므로 검토 없이 활성화해서는 안 됩니다.
schedule을 구성할 때 먼저 사용자에게 동기화가 매일 몇 시에 실행되어야 하는지 묻습니다. GitHub cron은 워크플로가 지원되는 timezone을 명시적으로 설정하지 않는 한 기본적으로 UTC를 사용합니다. 정시 0분에 작업을 예약하지 마십시오. GitHub 공식 문서에 따르면 매시간 시작 시 부하가 높아 예약된 작업이 지연되거나 충분히 높은 부하에서는 삭제될 수도 있습니다. 또한 일반적인 5분 마크를 피하기 위해 10, 15, 20, 30, 40 또는 45와 같은 5의 배수를 사용하지 마십시오. 1–59 사이에서 5의 배수가 아닌 분을 무작위로 선택하여 워크플로에 고정 값으로 작성합니다. 예를 들어 python -c 'import secrets; print(secrets.choice([m for m in range(1, 60) if m % 5]))'를 실행합니다. 여기서 "무작위"는 구성 생성 시에만 적용됩니다. 워크플로가 매 실행마다 동적 지연을 기다리게 하지 마십시오.
메인 또는 릴리스 브랜치
메인 또는 릴리스 브랜치는 최신 업스트림에서 시작하여 유지 관리 브랜치와 필요한 패치 브랜치를 고정된 순서로 통합합니다. 완전한 코드, 빌드, 테스트 및 릴리스 아티팩트를 제공합니다.
이 브랜치는 현재 다운스트림 통합 결과만 나타냅니다. 어떤 패치의 장기적인 유지 관리 소스가 아닙니다. 문제는 여기서 먼저 재현되고 분석될 수 있지만 수정 사항은 해당 패치 또는 유지 관리 브랜치로 돌아가야 하며, 그 후 통합 결과를 재생성해야 합니다.
릴리스 기록에서 각 패치는 하나의 명확하고 셀 수 있는 통합 커밋으로 나타나야 하며, 다운스트림 패치 수와 포크가 업스트림보다 뒤처진 커밋 수를 모두 확인할 수 있어야 합니다.
워크플로
1. 현재 상태 검사
시작하기 전에 저장소 자체의 유지 관리 및 기여 지침, 다운스트림 MAINTAIN.md(있는 경우) 및 이를 가리키는 README 알림을 읽습니다. 작업 트리, 원격, 현재 브랜치, 업스트림 관계 및 기존 동기화 및 릴리스 프로세스를 검사합니다. 커밋되지 않은 사용자 작업을 보존하거나 해결합니다. 허가 없이 정리하거나 덮어쓰지 마십시오.
2. 코딩 전 업스트림 이슈 및 풀 리퀘스트 확인
새로운 요청을 구현하거나 코드를 작성하기 전에 관련 논의 또는 구현을 위해 업스트림 이슈 트래커와 풀 리퀘스트를 검색합니다. 열린 이슈와 닫힌 이슈, 열린 PR, 초안 PR, 닫힌 PR, 병합된 PR을 확인합니다. 요청의 정확한 표현뿐만 아니라 관련 구성 요소 이름, 오류 메시지 및 합리적인 동의어도 검색합니다. 현재 상태를 확인하기 위해 연결된 이슈, 리뷰, 커밋 및 대체 PR을 충분히 추적합니다.
결과를 사용하여 다음 작업을 선택합니다:
- 업스트림이 이미 요구 사항을 구현한 경우 다운스트림 변경이 여전히 필요한지 결정하기 전에 적용 가능한 버전과 동작을 확인합니다.
- 활성 이슈 또는 PR이 이를 다루는 경우, 인식하지 못한 복제본을 만드는 대신 해당 작업에 기여, 테스트, 업데이트 또는 일시적으로 수행하는 것을 선호합니다.
- 이전 접근 방식이 거부, 되돌리기 또는 대체된 경우 새 구현을 제안하기 전에 명시된 이유를 이해합니다.
- 관련 업스트림 링크와 결론을 작업 계획, 패치 노트 또는 PR 설명에 기록하여 결정을 검토 가능하게 유지합니다.
관련 업스트림 이슈 또는 PR이 있는 경우 구현으로 직접 진행하지 마십시오. 먼저 실제 상태, 범위, 결정, 해결되지 않은 문제, 리뷰 피드백, 구현 상태 및 사용자 요청과의 관계를 확인합니다. 그런 다음 원시 링크 목록을 전달하는 대신 관련 업스트림 정보를 사용자에게 종합합니다. 무엇을 배웠는지, 현재 가정 및 계획에 어떤 영향을 미치는지, 원래 요청의 어떤 부분이 여전히 필요한지 명확히 설명합니다.
해당 조사가 작업의 범위, 접근 방식, 우선 순위, 소유권, 호환성 전략 또는 필요성을 변경할 수 있는 새로운 발견을 생성하는 경우 사용자에게 계획을 변경해야 하는지 명시적으로 묻습니다. 사용자가 계획을 유지하거나 수정할지 확인할 때까지 구현을 일시 중지합니다. 업스트림 논의를 기반으로 요청을 조용히 재해석하지 마십시오.
하나의 정확한 용어 검색 결과가 없다는 이유만으로 구현을 시작하지 마십시오. 먼저 합리적인 검색을 수행합니다. 관련 논의나 구현이 발견되지 않으면 해당 결과를 명시하고 계속 진행합니다.
3. 완전한 통합 결과에서 재현
먼저 현재 메인 또는 릴리스 브랜치에서 문제를 재현하여 사용자가 실제로 실행하는 패치 조합에서 어떻게 발생하는지 확인합니다.
분석 중에 다음을 구분합니다:
- 업스트림 자체의 문제.
- 하나의 독립 패치의 문제.
- 패치 간의 통합 문제. 개별 PR에 속하지 않는 경우
tmp/patch/<name>에 배치합니다. - CI, 패키징, 동기화 또는 다운스트림 문서의 문제.
4. 소유 브랜치 찾기 및 수정
동작을 담당하는 패치 브랜치를 찾고 해당 브랜치에서 수정 및 테스트를 완료합니다. 문제가 여러 패치 간의 호환성에 관한 것인 경우 tmp/patch/<name>을 생성하거나 업데이트합니다. 릴리스 자동화 또는 기타 다운스트림 유지 관리 작업에 관한 것인 경우 ci 브랜치를 수정합니다.
메인 또는 릴리스 브랜치에만 충돌 수정 또는 제품 수정을 커밋하지 마십시오. 업스트림에서 다음 재구축 시 손실되고 패치를 독립적으로 검토할 수 없게 됩니다.
5. 패치를 독립적으로 사용 가능하게 유지
저장소 규칙을 따라 최신 업스트림에 패치를 업데이트하고, 패치 브랜치에서 충돌을 해결하며, 해당 패치에 필요한 빌드 및 테스트를 실행합니다.
릴리스 브랜치의 숨겨진 변경 사항에 의존하지 않고 자체적으로 PR로 설명, 검토 및 제출할 수 있는지 확인합니다. 업스트림 PR이 이미 존재하는 경우에도 업데이트하고 업스트림 피드백에 응답하여 계속 유지 관리합니다.
6. 메인 또는 릴리스 브랜치 재구축
최신 업스트림을 다시 가져오고, 특정 업스트림 헤드에서 깨끗한 후보 브랜치를 만든 다음, ci 브랜치에서 선언한 고정 순서로 릴리스 오버레이, 일반 패치 및 필요한 tmp/patch/<name> 브랜치를 통합합니다.
각 일반 패치 및 임시 호환성 패치는 릴리스 기록에서 자체 명확한 통합 커밋을 생성해야 합니다. 저장소는 스쿼시 병합 또는 프로젝트에서 설정한 동등한 방법을 사용할 수 있지만 결과는 쉽게 검토하고 셀 수 있어야 합니다.
7. 사용 가능한 결과 검증
완전한 후보 버전에 대해 저장소의 필수 검사를 실행하여 최소한 다음을 다룹니다:
- 각 패치 자체에 대한 집중 테스트.
- 여러 패치를 결합한 후 통합 동작.
- CI, 패키징 및 다운스트림 문서가 올바른 브랜치에서 제공되는지 여부.
- 사용자가 실제로 얻는 코드 또는 아티팩트가 검증된 커밋에 해당하는지 여부.
후보 코드와 아티팩트가 모두 필요한 모든 검증을 통과한 후에만 원격 메인 또는 릴리스 브랜치를 업데이트합니다.
자동 동기화
자동 동기화의 목적은 오래된 릴리스 브랜치에 수정 사항을 계속 축적하는 것이 아니라 새로운 업스트림 헤드에서 정기적으로 사용 가능한 다운스트림 릴리스 결과를 재생성하는 것입니다.
동기화 프로세스는 다음을 수행해야 합니다:
- 저장소에서 허용하는 동시성 제어를 사용하여 두 개의 동기화 또는 릴리스 프로세스가 동시에 동일한 브랜치를 업데이트하지 못하도록 합니다.
- 최신 업스트림,
ci브랜치, 활성화된 모든 일반 패치 및 모든tmp/patch/<name>브랜치를 가져옵니다. - 해당 실행을 위해 명시적으로 선택된 업스트림 커밋에서 깨끗한 후보 브랜치를 만듭니다.
- 다운스트림 릴리스 오버레이, 일반 패치 및 임시 호환성 패치를
ci브랜치에 정의된 순서로 통합합니다. - 후보 브랜치에 대해 필요한 저장소 검사를 실행합니다.
- 검증에 성공하면 후보를 대상 브랜치로 푸시합니다. 검증에 실패하면 대상 브랜치를 업데이트하지 않고 이전 릴리스 결과를 유지합니다.
최종 참고 사항
다운스트림 포크를 유지하는 것은 별도의 병렬 코드베이스를 만드는 것이 아닙니다. 업스트림에 가깝게 유지하고, 각 패치를 고품질로 유지하며, 통합 결과를 지속적으로 검증하고, 변경 사항이 다시 업스트림으로 흘러갈 수 있는 경로를 제공하는 것입니다. 성공적인 다운스트림 포크는 사용자에게 즉각적인 가치를 제공하면서도 장기적으로 유지 관리 부담을 최소화합니다.