이 가이드라인은 glab CLI 참조 문서에 필요한 구조, 콘텐츠 및 언어 규칙을 정의합니다. gitlab-org/cli 프로젝트에서 make gen-docs로 생성되는 Markdown 파일에 특화된 규칙으로, 문서 스타일 가이드를 확장합니다.

다음과 같은 경우 이 가이드라인을 사용하세요:

• gitlab-org/cli에 새 glab 명령어를 추가할 때

• CLI 문서가 되는 Go 소스 문자열을 업데이트할 때

• CLI 문서를 추가하거나 변경하는 머지 리퀘스트를 리뷰할 때

CLI 문서 생성 방법#

CLI 문서는 gitlab-org/cli의 Go 소스 파일에서 생성됩니다. 생성기(make gen-docs)는 명령어마다 하나의 Markdown 파일을 생성하고 출력을 docs/source/에 저장합니다. 생성된 파일은 GitLab CLI (glab) 문서의 단일 진실 공급원(Single Source Of Truth, SSOT)입니다.

docs/source/에 있는 파일을 직접 편집하지 마세요. 모든 콘텐츠는 Go 소스에서 작성해야 합니다. 생성된 파일에 대한 변경은 다음에 make gen-docs를 실행할 때 덮어쓰입니다.

생성 출력에 영향을 주는 Go 소스 문자열을 변경한 경우, make gen-docs를 실행하고 업데이트된 파일을 머지 리퀘스트의 일부로 커밋하세요. check_docs_update CI/CD job은 make gen-docs를 실행하여 생성된 파일에 커밋되지 않은 변경 사항이 있으면 실패합니다.

커밋을 푸시하기 전에 문서 문제를 포착하려면 make bootstrap을 실행하여 Lefthook을 설치하세요. pre-commit 훅은 명령어 파일이 변경되면 문서를 재생성하고, 업데이트된 파일이 스테이징될 때까지 커밋을 차단합니다. 자세한 내용은 Lefthook을 사용한 Git 훅을 참조하세요.

페이지 구조#

생성된 모든 CLI 문서 페이지에는 다음 섹션이 이 순서대로 포함되어야 합니다:

• 제목(Title)

• 짧은 설명(Short description)

• 개요(Synopsis)

• 별칭(Aliases) (명령어에 별칭이 있는 경우)

• 예시(Examples)

• 옵션(Options)

• 상위 명령어에서 상속된 옵션(Options inherited from parent commands)

• 하위 명령어(Subcommands) (명령어에 하위 명령어가 있는 경우)

다음 표는 각 페이지 섹션과 이를 생성하는 Go 소스 필드 간의 매핑을 보여줍니다:

제목(Title)#

제목은 인라인 코드로 형식화된 전체 명령어 호출입니다. 예를 들면:

title: '`glab mr create`'

제목은 Go 소스 명령어 이름에서 생성됩니다. 수동으로 편집하지 마세요.

짧은 설명(Short description)#

짧은 설명은 Go 명령어 정의의 Short 필드에서 생성됩니다. 명령어가 수행하는 작업을 설명하는 단일 문장입니다.

• 명령형으로 작성하세요. 예를 들어: Create a new merge request.

• 제목을 중복하지 마세요.

• 마침표로 끝내세요.

• 실험적 명령어의 경우 문장 뒤에 (EXPERIMENTAL)을 추가하세요. 예를 들어: Create a new stacked diff. (EXPERIMENTAL)

개요(Synopsis)#

모든 새 명령어에는 개요(Synopsis)가 포함되어야 합니다. 개요는 Go 명령어 정의의 Long 필드에서 생성되며 짧은 설명에 들어갈 수 없는 확장된 컨텍스트를 제공합니다. 예를 들어, 명령어가:

• 사용 제약 조건이나 상호 배타적인 플래그를 가지고 있을 때

• 타입이 지정된 입력이나 특수 입력 형식을 허용할 때

• 컨텍스트에 따라 다르게 동작할 때 (예: 브랜치 파이프라인과 머지 리퀘스트 파이프라인)

• 최소 GitLab 버전이 필요할 때. 자세한 내용은 GitLab 버전 지원을 참조하세요.

• 실험적일 때

여러 제약 조건이나 입력 타입에는 목록을 사용하세요. 짧은 설명에 이미 있는 정보를 반복하지 마세요.

사용법 줄 규칙#

사용법 줄은 개요 섹션과 --help 출력에 표시됩니다. 위치 인수에는 다음 규칙을 사용하세요:

실험적 기능 및 베타 기능#

프로덕션 사용 준비가 되지 않은 기능을 표시하기 위해 internal/text/text.go에 두 가지 상수가 정의되어 있습니다:

• text.ExperimentalString: 실험적 기능에 사용합니다.

• text.BetaString: 베타 기능에 사용합니다.

text.ExperimentalString 또는 text.BetaString을 Long 필드에 추가하세요. 올바른 패턴은 Long 필드가 어떻게 정의되었는지에 따라 다릅니다:

• 연결(concatenation)을 사용하는 heredoc.Doc 또는 heredoc.Docf: 두 함수 모두 템플릿에서 후행 공백을 제거하므로, ExperimentalString의 앞에 붙은 개행 문자가 구분자 역할을 합니다. 명시적인 "\n"은 필요하지 않습니다:

Long: heredoc.Doc(`
    Your command description here.
`) + text.ExperimentalString,

• %s 플레이스홀더를 사용하는 heredoc.Docf: 상수를 형식 인수로 전달합니다. 상수의 앞에 붙은 개행 문자가 구분자를 제공합니다:

Long: heredoc.Docf(`
    Your command description here.
    %s`, text.ExperimentalString),

• 원시 문자열 리터럴: 리터럴은 제거되지 않으므로 닫는 백틱 앞에 명시적인 개행 문자로 끝내세요:

var longString = `Your command description here.
` + text.ExperimentalString

원시 문자열이 개행 문자로 끝나지 않으면 명시적인 "\n" 구분자를 추가하세요:

Long: `Your command description here.` + "\n" + text.ExperimentalString,

이렇게 하면 생성된 문서의 개요 섹션에 다음과 같은 텍스트가 생성됩니다:

This feature is an experiment and is not ready for production use.
It might be unstable or removed at any time.
For more information, see
https://docs.gitlab.com/policy/development_stages_support/.

베타 명령어의 경우 동일한 방식으로 text.BetaString을 사용하세요. 이렇게 하면 다음과 같이 생성됩니다:

This feature is in beta and might not be ready for production use.
It might be unstable and breaking changes can occur outside of major releases.
For more information, see
https://docs.gitlab.com/policy/development_stages_support/.

이 문자열을 Long 필드에 수동으로 복사하지 마세요. 항상 상수를 사용하여 향후 문구 변경이 모든 명령어에 일관되게 적용되도록 하세요.

개별 플래그만 실험적인 경우(전체 명령어가 아닌), 간단한 개요 메모를 추가하여 이를 나타내세요. 예를 들어:

The --publish-to-catalog flag is experimental and requires the
`ci_release_cli_catalog_publish_option` feature flag to be enabled for your project.

기능에 활성화해야 하는 기능 플래그가 필요한 경우, 이 요구 사항을 개요에 문서화하세요.

실험적 기능 수명 주기#

실험적 기능은 호환성 변경 없이 수정하거나 제거할 수 있습니다. 기능이 실험적 단계에서 일반적으로 사용 가능(GA) 상태로 전환될 때:

• 짧은 설명에서 (EXPERIMENTAL)을 제거하세요.

• Long 필드에서 text.ExperimentalString(또는 text.BetaString)을 제거하세요.

• 플래그 설명에서 (EXPERIMENTAL)을 제거하세요.

• make gen-docs를 실행하고 업데이트된 파일을 커밋하세요.

별칭(Aliases)#

명령어의 별칭을 나열합니다. 이 섹션은 Go 명령어 정의의 Aliases 필드에서 자동으로 생성됩니다. 수동으로 편집하지 마세요.

예시(Examples)#

예시 섹션은 Go 명령어 정의의 Example 필드에서 생성됩니다. 모든 명령어에는 실제 사용 사례를 보여주는 예시가 최소 하나 이상 포함되어야 합니다. 사용법 줄을 단순히 반복하는 예시는 사용하지 마세요.

• 사용 사례별로 예시를 그룹화하세요.

• 직관적이지 않은 예시에는 명령어 위의 줄에 # 설명 텍스트 형식의 인라인 주석을 달아주세요.

• 옵션이 많은 명령어의 경우 가장 일반적인 조합을 먼저 보여주세요.

예를 들어:

# Create a merge request and assign it to yourself
glab mr create -a @me -t "Fix the login bug"

# Create a draft merge request from the current branch
glab mr create --draft --fill

옵션(Options)#

옵션 섹션에는 명령어에 특화된 모든 플래그가 나열됩니다. 이 섹션은 Go 소스 플래그 정의에서 생성됩니다.

Go 소스에서 플래그 설명을 작성할 때:

• 대문자로 시작하세요.

• 마침표로 끝내세요.

• 사용자가 제공하는 값에는 꺾쇠 괄호 플레이스홀더를 사용하세요. 예를 들어: <username>, <branch>.

• 기본값이 true인 불리언 플래그의 경우, pflag는 생성된 Markdown 출력에 자동으로 (default true)를 추가합니다. 수동으로 추가하지 마세요. 기본값이 false인 불리언 플래그에는 기본값 주석이 필요하지 않습니다.

• 일반적인 값 타입에는 표준 메타 변수를 사용하세요:

• 출력 형식 플래그에는 -F, --output [text | json]을 표준 형식으로 사용하세요. 일부 명령어는 같은 명령어 내 다른 플래그와의 이름 충돌로 인해 다른 짧은 플래그를 사용합니다.

실험적 플래그#

플래그가 실험적인 경우, 설명 앞에 (EXPERIMENTAL)을 붙이세요. 예를 들어:

--publish-to-catalog    (EXPERIMENTAL) Publish the release to the GitLab CI/CD catalog.

또한 실험적 상태 및 기능 플래그 요구 사항을 설명하는 개요 메모를 추가하세요. 자세한 내용은 실험적 기능 및 베타 기능을 참조하세요.

상위 명령어에서 상속된 옵션#

이 섹션에는 --help 및 --repo와 같이 그룹 내 모든 하위 명령어에서 사용할 수 있는 플래그가 나열됩니다. 상위 명령어의 상속된 플래그에서 자동으로 생성됩니다. 수동으로 편집하지 마세요. 상속된 플래그에 대한 변경은 상위 명령어의 Go 소스에서 이루어져야 합니다.

하위 명령어(Subcommands)#

하위 명령어 섹션은 상위 명령어 인덱스 페이지(_index.md)에만 표시됩니다. 예를 들어 glab ci 및 glab mr 페이지에서 볼 수 있습니다. 각 하위 명령어 페이지로의 링크가 포함된 글머리 기호 목록으로 자동 생성됩니다. 수동으로 편집하지 마세요.

머지 리퀘스트 제목#

MR 제목은 commit-lint CI job에 의해 검증됩니다. squash on merge가 기본으로 활성화되어 있으므로, MR이 머지될 때 MR 제목이 커밋 메시지가 됩니다. 제목은 프로젝트의 기여 가이드라인에 정의된 conventional commits 형식을 따라야 합니다.

Front matter#

생성된 모든 페이지에는 front matter가 포함됩니다. stage 및 group 값은 생성기(cmd/gen-docs/docs.go)에서 모든 명령어에 대해 Create 및 Code Review로 하드코딩되어 있습니다. 생성된 파일에서 이 값을 편집하지 마세요. make gen-docs를 실행할 때마다 덮어쓰입니다.

환경 변수#

glab 동작에 영향을 주는 모든 환경 변수의 표준 참조는 gitlab-org/cli README의 환경 변수 섹션입니다. 여기에는 GitLab 접근 변수(예: GITLAB_TOKEN, GITLAB_HOST), glab 구성 변수(예: BROWSER, GLAB_NO_PROMPT, GLAB_GLAMOUR_STYLE), 그리고 이에 해당하는 config.yml 등가물과 기본값이 포함됩니다.

glab 동작에 전역적으로 영향을 주는 환경 변수는 Go 소스의 help:environment 어노테이션에서 생성된 루트 명령어 페이지에 문서화됩니다. 개별 명령어 페이지에서 전체 변수 목록을 중복하여 기재하지 마세요.

특정 명령어의 동작이 환경 변수에 의해 영향을 받는 경우에는 개요에서 참조하세요. 변수를 인라인 코드로 나열하고, 해당 명령어 컨텍스트에서의 효과를 설명하세요. 예를 들어:

If `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, or `OAUTH_TOKEN` are set,
they take precedence over the stored credentials.

사용 중단 가이던스는 사용 중단된 환경 변수를 참조하세요.

사용 중단(Deprecations)#

glab에서 플래그 또는 환경 변수를 사용 중단할 때는 다음 가이던스를 사용하세요.

사용 중단된 플래그#

MarkDeprecated로 플래그를 사용 중단할 때, Cobra는 메시지 앞에 고정된 접두사를 붙입니다:

Flag --<flag> has been deprecated, <your message>

Cobra의 접두사는 쉼표로 끝납니다. 메시지를 소문자 첫 글자로 시작하는 문장 연속으로 작성하고 마침표로 끝내세요. 예를 들어, use --output instead.는 다음과 같이 생성됩니다:

Flag --output-format has been deprecated, use --output instead.

사용 중단된 플래그에 직접적인 대체 플래그가 있는 경우 use --<replacement> instead.로 메시지를 끝내세요. 대체 플래그가 없는 경우에는 결과 동작을 설명하세요. 예를 들어, tracking is enabled by default..

사용 중단 메시지에서 now 또는 currently와 같은 시간 상대적 표현을 피하세요.

이 규칙은 REST API 사용 중단 가이던스와 병행하며, Cobra의 래퍼에 맞게 조정되었습니다.

사용 중단된 환경 변수#

환경 변수를 사용 중단하는 경우, root.go의 help:environment 어노테이션을 업데이트하세요. 모든 항목을 알파벳 순서로 유지하세요.

• 사용 중단된 변수 항목을 제거하세요.

• 대체 변수에 대한 새 항목을 전체 설명과 함께 추가하세요.

• make gen-docs를 실행하고 재생성된 파일을 커밋하세요.

• README의 변수 섹션에도 동일한 업데이트를 적용하세요.

GitLab 버전 지원#

glab은 공식적으로 GitLab 16.0 이상을 지원합니다. 명령어나 플래그가 올바르게 작동하기 위해 더 최신 버전의 GitLab이 필요한 경우, 개요에 이 요구 사항을 문서화하세요. 예를 들어:

This command requires GitLab 17.0 or later.

버전 관리 및 호환성 변경#

glab은 SemVer를 따릅니다. 버전 관리 규칙은 명령어와 플래그 문서 방식에 직접적인 영향을 미칩니다:

실험적 기능 및 베타 기능은 안정성이 보장되지 않으며 호환성 변경 없이 수정하거나 제거할 수 있습니다.

관련 항목#

• 문서 스타일 가이드

• GitLab CLI (glab) 문서

• REST API 리소스 문서화

• gitlab-org/cli README