설명서 버전 관리하기

GitHub Docs에서는 YAML 프런트매터 및 Liquid 연산자를 사용한 단일 소스 접근 방식을 사용하여 GitHub의 여러 버전을 지원합니다.

이 문서의 내용

GitHub Docs에서는, GitHub의 주요 제품 제공에 걸쳐 UI와 기능의 차이를 반영한 설명서의 버전을 제공합니다. 기여자는 버전 관리 구문을 사용하여 콘텐츠 범위를 특정 제품 제공 사항으로 지정할 수 있습니다.

버전 관리 구문은 독자가 사용하고 있는 제품에 적용되는 설명서의 버전을 수동으로 선택할 수 있게 합니다. GitHub Docs의 URL에는 버전 관리 정보도 포함되어, GitHub.com 및 GitHub Enterprise Server의 링크를 통해 사용자가 사용 중인 제품의 문서로 바로 이동할 수 있습니다.

버전 관리 방법 및 위치

GitHub Docs의 콘텐츠 버전 관리는 반복을 방지하고 산문을 건조(DRY)하게 유지하기 위한 단일 소스입니다. 문서의 경우 YAML 메타데이터를 사용하여 개별 Markdown 파일에 버전 관리를 적용한 다음, 파일의 산문 내에서 조건문을 사용하여 독자가 선택한 버전에 따라 표시할 텍스트를 사이트에 지시합니다. 단일 소싱은 각 버전의 콘텐츠를 반영한 별도 파일을 만드는 것과 대조됩니다.

GitHub Docs에 대한 버전 관리 구문에는 두 가지 유형이 있습니다.

  • YAML: content/의 Markdown 파일 내의 YAML 프런트 매터에서 가장 자주 사용되지만 data/의 여러 형식의 YAML 파일에서도 사용됩니다. 전체 콘텐츠에 대해 버전 관리를 표시하세요.

    versions:
  PRODUCT: 'VERSIONS'
  PRODUCT: 'VERSIONS'
  ...

    다음 예시에서는 GitHub.com에 대해 버전이 지정된 콘텐츠와 모든 버전의 GitHub Enterprise Server을(를) 보여줍니다.

    versions:
  fpt: *
  ghes: *

  • Liquid: content/과(와) data/reusables/의 Markdown 파일,data/variables/의 YAML 파일 내 변수 문자열 또는 data/glossaries/external.yml내의 문자열에 사용됩니다. 독자가 YAML 프런트 매터로 정의된 여러 버전이 있는 콘텐츠의 버전을 선택할 때 어떤 텍스트를 표시할지 표시하세요.

    • 제품 기반의 버전 관리:

      {% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}

    • 기능 기반의 버전 관리:

      {% ifversion FEATURE-NAME %} ... {% endif %}

다른 버전의 GitHub 정보

GitHub Enterprise Cloud 및 GitHub Enterprise Server 등 GitHub.com 플랜 사용자를 위한 버전별 설명서가 제공됩니다. 사이트에 여러 버전의 페이지가 있는 경우, 읽기 권한자는 페이지 맨 위에 있는 버전 선택기에서 버전을 선택할 수 있습니다.

GitHub.com

GitHub.com에 대한 설명서에는 두 가지 가능한 버전이 있습니다.

무료, Pro 또는 Teams 플랜

GitHub.com의 무료, Pro 또는 Teams 플랜은 free-pro-team@latest을 사용하세요. 약식 이름은 fpt입니다.

GitHub Enterprise Cloud

GitHub Enterprise Cloud에는 enterprise-cloud@latest을 사용하세요. 약식 이름은 ghec입니다.

GitHub Enterprise Server

GitHub Enterprise Server에 대한 설명서에는 여러 버전이 있으며 두 가지 유형으로 나눌 수 있습니다. _지원되는 출시_에 대한 설명서(한 번에 네 개 지원), 그리고 _사용되지 않는 출시_에 대한 설명서(Docs 사이트에서는 연결되지 않지만 이러한 문서의 "고정" 스냅샷이 계속 지원되므로 URL을 알고 있으면 계속 액세스할 수 있음)입니다. 목록은 lib/enterprise-server-releases.js(을)를 참조하세요.

버전 이름은 enterprise-server@<release>입니다. 약식 이름은 ghes입니다. Liquid 조건부에서, ghes > 3.0과(와) 같은 범위를 지정할 수 있습니다. 자세한 내용은 "Liquid 조건부 운영자 버전 관리"를 참조하세요.

YAML 프런트매터의 버전 관리

파일의 프런트매터 내 versions 속성을 사용하여 문서가 어느 제품에 대하여 표시될지 정의할 수 있습니다. 인덱스 파일에는 versions 속성이 필요하지만, 이는 하위 항목 버전에 따라 자동으로 버전이 지정됩니다.

예를 들어, 다음 YAML 프런트매터는 GitHub Enterprise Server 2.20 이상 및 무료, Pro 또는 Teams에 대한 문서 버전을 지정합니다.

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=2.20'

다음 예시에서는 지원되는 모든 버전의 GitHub Enterprise Server에 대한 문서 버전을 지정합니다.

title: Downloading your license
versions:
  ghes: '*'

다양한 릴리스에 대한 페이지 버전을 관리할 수도 있습니다. 다음 예시에서는 GitHub.com의 페이지 버전을 지정하고, GitHub Enterprise Server은(는) 버전 3.1 및 3.2만 해당합니다.

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>=3.1 <3.3'

Liquid 조건부 연산자를 사용하여 버전 관리하기

Liquid 템플릿 언어(특히, Node.js 포트)와 사용자 지정 {% ifversion ... %} 태그를 사용하여 설명서의 버전을 만듭니다.

페이지의 YAML 프런트매터 내에서 versions 키에 여러 제품을 정의하는 경우, Markdown의 조건부 연산자 ifversion/else(또는ifversion/elsif/else)를 사용하여 사이트가 특정 제품에 대한 페이지의 콘텐츠를 렌더링하는 방법을 제어할 수 있습니다. 예를 들어 기능에서 GitHub.com에 대한 옵션이 GitHub Enterprise Server보다 많을 수 있으므로, versions 프런트매터를 통해 콘텐츠를 적절하게 버전을 지정하고, Liquid 조건부를 사용하여 GitHub.com에 대한 추가 옵션을 설명할 수 있습니다.

참고:

  • 제품 기반 버전 관리 및 기능 기반 버전 관리에 ifversion을(를)사용하세요.
  • if 또는 unless을 사용하지 마세요.
  • elsif을 사용하고 else if는 사용하지 않습니다. Liquid는 else if을 인식하지 않고 else if 블록 안에 있는 콘텐츠를 렌더링하지 않을 것입니다.

비교 연산자

번호가 매겨진 출시(fpt과 ghec처럼)가 없는 버전의 경우 다음 두 가지 옵션이 있습니다.

  • {% ifversion ghec %}
  • {% ifversion not ghec %}

번호가 매겨진 출시(현재 ghes만 해당)가 있는 버전의 경우, 모든 출시에서 사용할 수 있거나 출시에서 사용할 수 없는 콘텐츠에 대해 동일한 작업을 수행할 수 있습니다.

  • {% ifversion ghes %}
  • {% ifversion not ghes %}

특정 출시에서만 사용할 수 있거나 사용할 수 없는 콘텐츠를 표시해야 하는 경우, 다음 운영자를 사용할 수 있습니다.

연산자의미예시
=다음과 같음{% ifversion ghes = 3.0 %}
>최신 버전{% ifversion ghes > 3.0 %}
<이전 버전{% ifversion ghes < 3.0 %}
!=같지 않음{% ifversion ghes != 3.0 %} (not 범위에서 사용하지 않음)

Liquid 운영자 ==, >= 및 <=은(는) GitHub Docs에서 지원되지 않습니다.

논리 연산자

조건이 true이면 모든 피연산자가 true여야 하는 경우, 다음 운영자 and을(를) 사용하세요.

{% ifversion ghes > 2.21 and ghes < 3.1 %}

조건이 true가 되려면 하나 이상의 피연산자가 true여야 하는 경우, 다음 운영자 or을(를) 사용하세요.

{% ifversion fpt or ghes > 2.21 %}

운영자 && 또는 ||는 사용하지 않습니다. Liquid는 이를 인식하지 못하며 의도한 버전에서 콘텐츠가 렌더링되지 않습니다.

공백 컨트롤

목록에서 Liquid 조건을 사용하는 경우 공백 컨트롤 문자를 사용하여 목록 렌더링을 중단하는 줄 바꿈 및 기타 공백을 추가하는 것을 방지할 수 있습니다.

왼쪽, 오른쪽 또는 양쪽에 하이픈(-)을 추가하여 해당 쪽에 줄 바꿈이나 다른 공백이 없어야 함을 나타냅니다.

{%- ifversion fpt %}

예를 들어 다음과 같이 절차의 한 단계를 버전화하는 대신 이전 단계의 끝에서 시작하는 단계에 대한 리퀴드 버전 관리를 추가할 수 있습니다:

1. This step is for all versions{% ifversion ghes %}
1. This step is for GHES only{% endif %}
1. This step is for all versions

Liquid 버전 관리를 자체 줄에 포함하고 공백 컨트롤을 사용하여 Liquid 태그 왼쪽의 줄 바꿈을 제거할 수 있습니다. 이렇게 하면 목록의 렌더링을 중단하지 않고 원본을 훨씬 쉽게 읽을 수 있습니다.

1. This step is for all versions
{%- ifversion ghes %}
1. This step is for GHES only
{%- endif %}
1. This row is for all versions

기능 기반 버전 관리 방법

새 변경 내용 또는 기능을 문서화하는 경우, 기능 기반의 버전 관리를 사용하세요.

소수의 기능 및 변경 내용은 언제나 하나의 제품에만 적용됩니다. 대부분의 기능은 GitHub.com에 도입되며 이후 모든 제품에 적용됩니다. 일반적으로 변경 내용은 GitHub.com(GitHub Enterprise Cloud 포함)에서 GitHub Enterprise Server(으)로 "이동"합니다.

기능 기반 버전 관리에서는 이름이 붙은 "기능 플래그"를 제공하여 설명서의 유지 보수 및 버전 관리를 간소화합니다. 단일 기능 이름(또는 "플래그")을 붙여서 콘텐츠 전체에서 산문을 그룹화하고 버전을 지정할 수 있습니다. 추가 제품에 대한 기능의 경우 data/features/ 안의 파일에서 YAML 버전 관리만 변경하면 됩니다.

기능 관리

각 기능은 data/features/의 개별 YAML 파일을 통해 관리됩니다.

참고: 테스트에 사용되므로 data/features/placeholder.yml은 삭제하지 마세요.

신규 기능을 생성하려면, 먼저 이 디렉터리에서 사용하려는 기능 이름을 사용하여 새 YAML 파일을 만드세요. meow라고 명명된 기능의 경우 data/features/meow.yml이 됩니다.

기능을 사용할 수 있는 버전의 짧은 이름과 함께 YML 파일에 versions 블록을 추가하세요. 예시:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>3.1'

형식 및 허용되는 값은 프런트매터 버전 속성과 동일합니다. 자세한 내용은 github/docs 리포지토리 추가 정보의 "버전"을 참조하세요.

Liquid 조건부

이제 콘텐츠 파일에서 {% ifversion meow %} ... {% endif %}를 사용할 수 있습니다!

프런트매터

콘텐츠 파일의 프런트매터에서 기능을 사용할 수도 있습니다.

versions:
  feature: 'meow'

versions 아래에서 하나의 feature 항목만 사용할 수 있으며 feature의 값에는 하나의 기능 이름만 포함될 수 있습니다.

프런트매터에서 기능 기반 버전 관리 및 표준 버전 관리를 결합할 수 있습니다. 이렇게 하면 이 문서는 기능 기반 버전 관리 파일에 지정된 모든 버전의 상위 집합과 Markdown 파일에 직접 포함됩니다. 예를 들어 현재 GHEC에서만 사용할 수 있는 기능이 있을 수 있으며 해당 기능이 기능 기반 버전 관리에서 지정됩니다. 그러나 이 기능에 대한 "정보" 문서를 FPT 문서에도 표시하려고 하는 경우 프런트매터의 versions 블록에 fpt 및 feature(을)를 추가할 수 있습니다.

versions:
  fpt: '*'
  feature: 'some-new-feature'

모범 사례

버전이 지정된 콘텐츠는 독자뿐만 아니라 콘텐츠에 기여하거나 검토하는 모든 사용자에게도 영향을 줍니다. 다음은 버전 관리 구문에 대한 쓰기, 읽기 및 검토 환경을 개선하기 위한 몇 가지 팁입니다. 이러한 사례 중 어느 것도 필수적이지 않으며 에지 및 코너 사례를 찾을 수 있지만, 이 사례는 버전 관리에서 생각하는 데 도움이 되는 유용한 경험적 접근에서 의도된 것입니다.

불필요한 버전 관리 방지

독자 입장에서는, 일반적인 이해를 얻는 것은 특정 제품이나 계획의 차이를 정확하게 반영하는 세부 정보를 읽는 것보다 더 중요합니다. 개념적 또는 절차적 콘텐츠에서, 버전 관리 구문이 필요하지 않은 일반적인 방식으로 UI의 기능 또는 부분을 설명해 보세요. 이렇게 하면 유지 관리가 쉬운 것 외에도, 여러 제품에 대한 설명서를 참조하는 독자들의 이해를 강화합니다.

  • "버전 관리 없이 모든 제품에 적용하는 방식으로 이 콘텐츠를 작성할 수 있을까?" 하고 자문해 보세요.
  • 스크린샷을 만드는 데 필요한 노력을 감안해서, 가능하면 스크린샷의 버전 관리를 피해 보세요. UI 복사본 간 사소한 차이는 이해하는 데에 영향을 미치지 않을 수 있습니다. 제품별 텍스트 또는 UI 요소가 있지만 스크린샷이 여전히 유용한 컨텍스트를 제공하는 경우, 스크린샷의 버전 관리가 의미 있는 정도의 이해에 영향을 주는지 자문해 보세요.
  • 특정 제품에 대한 버전 관리 없이 독자에게 개념을 설명하거나 절차를 안내할 수 있는 경우 산문을 버전화하지 마세요.

기존 콘텐츠 파일을 수정할 때, 초기에 그리고 자주 기존의 버전 관리를 검토하세요

기존 버전 관리의 인식 상태를 유지하면 관련 버전 관리 설명을 작성하는 데 도움이 되며, 새 콘텐츠를 정확하게 버전 관리하도록 기억하는데 도움을 줄 수 있습니다.

  • 편집을 시작하는 즉시 프런트 매터에서 전체 페이지의 버전을 검토하세요.
  • 편집 중인 콘텐츠에 대한 버전 관리를 검토하세요.
  • 렌더링된 버전의 변경 내용을 검토하고, 자체 검토의 일환으로 페이지에 사용 가능한 각 버전으로 전환하세요.

가능한 한 반복하지 마세요

문장이나 단락 내에서 버전 관리 구문을 사용하여 두 가지 다른 플랜이나 제품에 대한 산문을 구분하세요. 기여자는 버전 관리 설명을 사용하여 한 단락만 편집할 수 있으며, 대신 버전이 지정된 텍스트의 큰 블록을 고려하고 유사하지만 버전이 다른 산문을 두 곳에서 수정할 필요가 없습니다. 검토자는 동일한 제안을 여러 위치에 둘 필요 없이 변경 사항을 한 번에 제안할 수 있습니다. 그러나 동작이 극적으로 다르거나 문장이나 단락 내에서 버전 관리가 복잡해지거나 기여자가 구문 분석하기가 어려워지면, 반복해서 산문을 더 쉽게 유지 관리할 수 있도록 하세요.

  • 문장이나 전체 단락이 반복되는 것을 방지하려면 단락 내에서 버전 관리 구문 인라인을 사용하세요.

    {% ifversion fpt %} 무언가 {% elsif ghec %} 다른 무언가 {% endif %}을(를) 수행할 수 있습니다.

  • 문장이나 단락 내에서 버전 관리 구문을 많이 사용하지 않고 작성하거나 읽는 것이 복잡한 산문의 경우, 각 관련 제품에 대한 버전 블록에서 전체 단락을 반복하는 것이 좋습니다.

    {% ifversion fpt %}

    무료, Pro 또는 Teams 플랜을 사용하는 경우, 할 수 있는 것들이 있습니다. 무료, Pro 또는 Teams 플랜을 사용하여 수행할 수 있는 일에 대한 자세한 내용은 다음과 같습니다...

    {% elsif ghec %}

    GitHub Enterprise Cloud를 사용하는 경우, 할 수 있는 것들이 있습니다. GitHub Enterprise Cloud를 사용하여 수행할 수 있는 일에 대한 자세한 내용은 다음과 같습니다...

    {% endif %}

명시적이어야 하며, 암시적이면 안 됩니다

콘텐츠에서 설명하는 제품을 정확히 알고 있는 경우, 해당 제품에 대해 명시적으로 버전을 지정합니다. not과(와) 같은 구문, 특히 else는(은) 정확하지 않을 수 있습니다. not과 else의 최종 결과는 각 문서의 프런트 매터에 따라 달라지므로, 기여자는 이 버전 관리에서 산문을 이해하기 위해 더 많은 조사를 수행해야 합니다. 이렇게 하면 오류가 발생할 수 있습니다. 암시적 버전 관리의 복잡성은 재사용 가능 항목에서 증가하는데, 재사용 가능한 문서를 참조하는 문서는 버전 관리가 다르므로 not 또는 else의 평가가 다를 수 있습니다. 또한 GitHub에서 새 제품을 도입할 때 GitHub Docs에 새 버전을 도입하기도 하는데, 그러면 기존 문서에 새 버전을 추가할 때 not과(와) else의 최종 결과가 변경됩니다.

  • GitHub은(는) 네 개의 제품을 제공하므로 GitHub Docs은(는) 언제든지 총 여덟 개 버전에 대한 설명서를 표시할 수 있습니다.
  • 편집을 시작할 때 전체 문서의 버전 관리 내용을 검토해서, Liquid 설명에서 어떻게 not과(와) else가(이) 동작하는지, 또는 프런트 매터에서 새 버전을 사용할 때 어떻게 변경하는지를 이해하는 데 도움이 될 수 있습니다.

콘텐츠 디자인 및 만들기를 통해 작업할 때 버전 관리를 확인하고 통신하세요

원래 의도한 출시에 변경 내용이 포함되지 않는 경우가 있습니다. 출시 및 개선 사항 모두에 대해 콘텐츠 디자인 및 생성 전반에 걸쳐 버전 관리를 확인하여 검토자의 시간을 절약하고 보다 정확한 콘텐츠를 보장할 수 있습니다.

  • 콘텐츠 디자인을 버전 관리하고, 콘텐츠 만들기에 대한 관련자 검토를 요청할 때 버전 관리 검사를 두 번 하세요.
  • 다른 작성자 및 관련자가 더 쉽게 검토할 수 있도록 하세요. 검토 요청의 버전 간 차이점을 지적하고 필요한 경우 렌더링된 특정 버전의 콘텐츠에 연결합니다.
  • 신뢰하되, 확인하세요.

테스트하고, 테스트하고, 다시 테스트하세요

콘텐츠를 작성하든 콘텐츠를 검토하든, 콘텐츠 디자인 계획 및 영향을 받는 제품에 주의하고, 준비 또는 개발 환경에서 렌더링된 콘텐츠가 각 제품을 정확하게 설명하는지 확인합니다.