Microsoft Learn의 기여 기본 사항

  • 6분

기여 프로세스를 이해하고 완료하는 데 도움이 되는 몇 가지 용어를 알아야 합니다. 내부적으로 일어나는 모든 일을 알 필요는 없지만, 기여가 어떻게 작동하는지에 대한 일반적인 개요를 보면 프로세스가 그런 방식으로 작동하는 이유를 이해하는 데 도움이 됩니다.

Microsoft Learn 및 GitHub 기본 사항

Microsoft Learn에는 다양한 기여자가 저장하고 정기적으로 액세스해야 하는 수천 개의 문서, 학습 모듈, 웹 페이지 등이 포함되어 있습니다. Microsoft Learn은 GitHub를 사용하여 이 콘텐츠의 대부분을 저장합니다. GitHub는 분산 버전 제어 시스템인 Git을 사용하여 프로젝트를 저장하고 다양한 프로젝트 목표와 일정을 가진 여러 관련자 간의 협업을 촉진하는 플랫폼입니다. Git 및 GitHub 소프트웨어를 사용하면 의도치 않게 다른 사람의 작업을 방해하지 않고 동일한 프로젝트에서 다른 기여자와 동시에 작업할 수 있으며 잠재적으로 동일한 콘텐츠를 동시에 작업할 수 있습니다.

콘텐츠는 GitHub에서 호스트되는 Git 리포지토리(repos)의 파일에 저장됩니다. 리포지토리는 프로젝트의 파일과 파일 수정 버전 내역을 포함하는 스토리지 단위입니다. 리포지토리는 퍼블릭 또는 프라이빗일 수 있으며 Microsoft Learn은 두 가지가 혼합되어 구성됩니다. GitHub 계정을 설정하면 누구나 퍼블릭 리포지토리에 기여할 수 있습니다. 프라이빗 리포지토리는 Microsoft 직원이거나 특별 권한을 부여받은 기여자만 사용할 수 있습니다.

GitHub 리포지토리에 저장된 Microsoft Learn 콘텐츠를 편집합니다.

모든 프로젝트에서 GitHub는 기본 리포지토리와 모든 포크를 호스팅합니다. 포크는 기여자가 자신의 작업을 위해 만드는 기본 리포지토리의 복사본입니다. 포크는 게시된 콘텐츠를 보호하는 GitHub의 방법 중 하나입니다. GitHub는 기본 리포지토리의 게시된 라이브 분기에서 콘텐츠를 직접 편집하는 대신 포크에 대한 해당 콘텐츠의 스냅샷을 만들므로 여기서 변경할 수 있습니다.

GitHub 리포지토리에는 하나 이상의 분기가 포함되어 있습니다. 분기는 프로젝트의 콘텐츠 집합을 구성하는 파일과 폴더가 포함된 스토리지 단위입니다. 기본 리포지토리이든 포크이든 모든 리포지토리에는 기본 포크(일반적으로 "main"이라고 함)와 기본 분기에 다시 병합될 하나 이상의 분기가 포함되어 있습니다. 기본 분기는 프로젝트의 현재 버전이자 “단일 데이터 소스”(single source of truth)로 사용됩니다. 리포지토리의 나머지 분기들은 부모인 마스터 분기에서 생성됩니다.

Diagram showing a working branch off of the main branch in a GitHub repo. Changes are made in the working branch then merged back to main.

퍼블릭 리포지토리에 있는 설명서 문서를 편집하는 것은 단추 하나만 누르면 시작되는 것처럼 보일 수 있지만 그 이면에는 몇 가지 일이 일어나고 있습니다. 브라우저 기반 편집 프로세스를 시작하면 리포지토리 포크가 만들어져(아직 없는 경우) 변경 내용에 사용됩니다. 포크의 분기 내에서 편집하면 나중에 기본 리포지토리의 라이브 분기에 병합되어 변경 내용을 모두가 사용할 수 있습니다.

끌어오기 요청 만들기

이 병합은 어떻게 발생하나요? GitHub(구체적으로 주요 리포지토리의 소유자와 문서 작성자)에게 편집 내용이 마무리되어 검토, 게시 및 전 세계가 볼 수 있도록 준비가 되었음을 알려야 합니다. 이렇게 하려면 끌어오기 요청을 작성하여 제출합니다.

PR(끌어오기 요청)은 작업 중이던 포크의 분기에서 라이브 리포지토리의 기본 "메인" 분기로 변경 내용을 병합하라는 제안입니다. 퍼블릭 리포지토리에서 작업할 때 끌어오기 요청은 병합되기 전에 항상 검토자가 검토합니다. 병합 호환성 및 빌드 유효성 검사와 같은 일부 자동화된 검사가 있을 수도 있습니다. 검토가 완료되고 문제가 해결되면 변경 내용이 라이브 분기에 병합되고 Microsoft Learn에서 사용할 수 있게 됩니다!

문서화에 대한 사소한 기여를 위한 워크플로

요약하자면, GitHub의 웹 편집기를 사용하여 Microsoft 설명서를 약간 변경할 때 다음과 같은 일반적인 단계를 따르게 됩니다.

Diagram of the contribution process for contributing to open source documentation on Microsoft Learn.

  1. 편집하기 위해 브라우저에서 파일을 열면 퍼블릭 리포지토리의 포크가 자동으로 만들어집니다. 포크에는 종종 패치 분기라고 불리는 분기도 만들어집니다.
  2. 파일을 변경합니다.
  3. 변경 내용을 검토하고 병합하도록 제안하는 끌어오기 요청을 만듭니다.
  4. PR은 모든 문제를 해결하고 모든 검토를 통과해야 합니다.
  5. PR은 라이브 리포지토리의 기본 분기에 병합되고 변경 내용은 Microsoft Learn에 게시됩니다.

다음으로, 각 단계를 더 자세히 살펴보고 이를 수행하는 방법을 알아보겠습니다.