문서 테스트

GitLab 문서는 코드로 저장되며 코드처럼 처리됩니다. 문서의 표준과 품질을 유지하기 위해 코드에 사용되는 것과 유사한 프로세스를 사용합니다.

.md 파일의 변경 사항을 포함하는 Merge Request은 다음 CI/CD 작업을 실행합니다.

  • docs-lint markdown: Vale를 포함한 여러 유형의 테스트를 실행합니다:
  • docs-lint links: 문서 스위트에서 내부 링크의 유효성을 확인합니다.
  • ui-docs-links lint: app/views 파일과 같은 UI 요소의 링크의 유효성을 확인합니다.

lint-doc.sh의 테스트

/scripts/lint-doc.sh에 있는 테스트는 Vale 및 markdownlint로 테스트할 수 없는 페이지 내용 문제를 찾습니다. lint-doc.sh 테스트 중 이러한 테스트 중 하나라도 실패하면 docs-lint markdown 작업이 실패합니다.

  • Curl (curl) 명령은 -h와 같은 짧은 형식 대신 --header와 같은 긴 형식 옵션을 사용해야 합니다.
  • 문서 페이지에는 페이지 소유를 나타내는 front matter가 포함되어야 합니다.
  • 검색 색인 및 grep 작업에서 불규칙성을 일으킬 수 있는 비표준 유니코드 공백 문자 (NBSP, NNBSP, ZWSP)를 사용해서는 안 됩니다.
  • CHANGELOG.md에 중복된 버전이 포함되어서는 안 됩니다.
  • doc/ 디렉터리의 파일은 실행 파일이어서는 안 됩니다.
  • README.md 대신 index.md를 사용해야 합니다.
  • 디렉터리와 파일 이름은 대시(-) 대신 밑줄(_)을 사용해야 합니다.
  • 디렉터리와 파일 이름은 소문자여야 합니다.
  • Mermaid 차트는 오류 없이 렌더링되어야 합니다.

Mermaid 차트 린팅

Mermaid는 코드에서 차트와 다이어그램을 작성합니다.

스크립트(scripts/lint/check_mermaid.mjs)는 Markdown 파일에 변경 사항이 포함된 모든 Merge Request에서 lint-doc.sh 검사 중에 실행됩니다. 스크립트는 Markdown 파일 중 하나라도 Mermaid 구문 오류가 있을 경우 오류를 반환합니다.

Mermaid 차트를 디버그하는 데 도움을 주려면 Mermaid 라이브 에디터를 사용하세요.

docs-lint links의 테스트

.md 파일에 변경 사항이 포함된 Merge Request은 docs-lint links 작업을 실행하며, 이 작업은 두 가지 유형의 링크 확인을 실행합니다. 두 경우 모두, http 또는 https로 시작하는 대상을 가진 링크는 외부 링크로 간주되어 건너뜁니다:

  • bundle exec nanoc check internal_links: 내부 페이지로의 링크를 테스트합니다.
  • bundle exec nanoc check internal_anchors: 내부 페이지의 주제 제목 앵커로의 링크를 테스트합니다.

이러한 테스트에서의 실패는 나머지 문제 발견! 영역의 테스트 결과의 끝에 표시됩니다. 예를 들어, internal_anchors 테스트에서의 실패는 다음 형식을 따릅니다: 

[ ERROR ] internal_anchors - Broken anchor detected!
  - source file `/tmp/gitlab-docs/public/ee/user/application_security/api_fuzzing/index.html`
  - destination `/tmp/gitlab-docs/public/ee/development/code_review.html`
  - link `../../../development/code_review.html#review-response-slo`
  - anchor `#review-response-slo`
  • Source file: 오류가 포함된 파일의 전체 경로입니다. gitlab 리포지터리에서 해당 파일을 찾으려면 /tmp/gitlab-docs/public/ee를 doc로, .html을 .md로 대체하면 됩니다.
  • Destination: 테스트에서 발견되지 않는 파일의 전체 경로입니다. gitlab 리포지터리에서 해당 파일을 찾으려면 /tmp/gitlab-docs/public/ee를 doc로, .html을 .md로 대체하면 됩니다.
  • Link: 스크립트가 시도한 실제 링크입니다.
  • Anchor: 있을 경우, 스크립트가 찾으려고 시도한 주제 제목 앵커입니다.

오류가 발견된 각 페이지에서 같은 깨진 링크의 여러 인스턴스를 확인하세요. 특정한 깨진 링크가 페이지에 여러 번 나타나더라도, 테스트는 한 번만 보고합니다.

ui-docs-links lint 작업은 UI 요소(app/views 파일 등)에서의 모든 문서 링크가 유효한 페이지와 앵커를 연결하는지 테스트하기 위해 haml-lint를 사용합니다.

문서 린터 설치

문서 스타일 가이드라인을 준수하고 문서에 추가된 콘텐츠를 개선하기 위해 문서 린터를 설치하고 코드 에디터와 통합하세요. 최소한 markdownlint와 Vale을 설치하여 빌드 파이프라인에서 실행되는 검사와 일치시키세요. 두 도구는 코드 에디터와 통합할 수 있습니다.

로컬에서 문서 테스트 실행

로컬에서 변경 내용 미리보기와 유사하게, 로컬 컴퓨터에서도 문서 테스트를 실행할 수 있습니다. 이는 다음과 같은 이점이 있습니다:

  • 피드백 루프를 빠르게 만듭니다. CI/CD 파이프라인을 기다리지 않고 브랜치의 변경 사항에 문제가 있는지 알 수 있습니다.
  • 비용을 낮춥니다. 로컬에서 테스트를 실행하는 것이 GitLab이 사용하는 클라우드 인프라에서 테스트를 실행하는 것보다 저렴합니다.

중요한 점은 다음과 같습니다:

  • 도구를 최신 상태로 유지하고 CI/CD 파이프라인에서 사용되는 버전과 일치시키세요.
  • 린터, 문서 링크 테스트 및 UI 링크 테스트를 CI/CD 파이프라인에서 실행되는 방식과 동일하게 실행하세요. CI/CD 파이프라인에서 사용하는 것과 다를 수 있는 도구의 기본 구성을 사용하는 것이 중요합니다.

로컬에서 Vale 또는 markdownlint 실행

Vale와 markdownlint 설치 및 구성 지침을 참조하세요.

로컬에서 lint-doc.sh 실행

lint-doc.sh 테스트를 로컬에서 실행하려면 Rake 작업을 사용하세요.

필요 사항:

  • 컴퓨터에 필요한 린트 도구가 설치되어 있거나, 이러한 도구가 사전에 설치된 이미지를 사용하기 위해 도커 또는 containerd 설치가 작동 중이어야 합니다.
  1. gitlab 디렉터리로 이동하세요.

  2. 다음과 같이 실행하세요: 

    rake lint:markdown

원하는 파일이나 디렉터리에 대한 단일 파일을 지정하려면 다음과 같이 실행하세요: 

MD_DOC_PATH=path/to/my_doc.md rake lint:markdown

출력은 다음과 유사해야 합니다: 

=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings, and 0 suggestions in 1 file.
✔ Linting passed

로컬에서 문서 링크 테스트 실행

문서에서 링크를 테스트하려면 다음을 실행하세요:

  1. gitlab-docs 디렉터리로 이동하세요.

  2. 다음 명령을 실행하세요: 

    # 깨진 내부 링크를 확인합니다
bundle exec nanoc check internal_links
   
# 깨진 외부 링크를 확인합니다 (완료하는 데 많은 시간이 걸릴 수 있습니다).
# 이 테스트는 실패해도 되며, gitlab-docs 프로젝트에서만 실행됩니다
bundle exec nanoc check internal_anchors

로컬에서 UI 링크 테스트 실행

GitLab UI에서 문서 링크를 로컬에서 테스트하려면 다음을 수행하세요:

  1. 터미널 창에서 gitlab 디렉터리를 엽니다.

  2. 다음을 실행하세요: 

    bundle exec haml-lint -i DocumentationLinks

이 테스트를 처음 실행할 때 오류가 발생하면 bundle install을 실행하여 GitLab의 의존성을 설치한 후 다시 시도하세요.

만약 링크를 테스트하기 위해 모든 의존성을 설치하고 싶지 않다면 다음을 수행할 수 있습니다:

  1. 터미널 창에서 gitlab 디렉터리를 엽니다.

  2. haml-lint를 설치합니다: 

    gem install haml_lint

  3. 다음을 실행하세요: 

    haml-lint -i DocumentationLinks

이 과정으로 매뉴얼으로 haml-lint를 설치하면 자동으로 업데이트되지 않으며, GitLab에서 사용하는 버전과 일치하는지 확인해야 합니다.

린터 구성 업데이트

Vale 및 markdownlint 구성은 각 프로젝트의 소스 제어에 있으므로 업데이트는 각 프로젝트에 커밋되어야 합니다.

gitlab 프로젝트의 구성은 진실의 원천으로 취급되어야 하며, 모든 업데이트는 먼저 해당 프로젝트에서 이루어져야 합니다.

정기적으로 gitlab 프로젝트에서 Vale 및 markdownlint 구성에 대한 변경 사항을 다른 프로젝트로 동기화해야 합니다. 지원되는 프로젝트 각각에서 다음을 수행하세요:

  1. 새 브랜치를 생성하세요.
  2. 해당 브랜치로부터 gitlab 프로젝트의 구성 파일을 복사하여 해당 프로젝트의 이전 구성을 덮어쓰기하세요. gitlab 프로젝트의 프로젝트별 변경 사항이 포함되지 않도록 주의하세요. 예를 들어, RelativeLinks.yml은 특정 프로젝트에 대해 하드코딩되어 있습니다.
  3. 새 Merge Request를 생성하고 기술 작성자에게 리뷰 및 머지를 요청하세요.

린팅 이미지 업데이트

린트 테스트는 CI/CD 파이프라인에서 gitlab-docs 컨테이너 레지스트리의 이미지를 사용하여 실행됩니다.

의존성의 새 버전(예: 새로운 Ruby 버전)이 출시되면, 이미지를 해당 새 버전을 사용하도록 업데이트해야 합니다. 그런 다음, 각 문서 프로젝트의 구성 파일을 새 이미지를 가리키도록 업데이트할 수 있습니다.

린팅 이미지를 업데이트하려면 다음을 수행하세요:

  1. gitlab-docs에서 .gitlab-ci.yml을 업데이트하기 위한 Merge Request를 엽니다. (예시 MR)
  2. 머지되면, Build docs.gitlab.com every hour 일정된 파이프라인을 시작하세요.
  3. 시작한 파이프라인으로 이동하여, 관련된 build-images 작업을 매뉴얼으로 실행하세요. 예를 들어, image:docs-lint-markdown입니다.
  4. 작업 출력에서 새 이미지의 이름을 확인하세요. (예시 작업 출력)
  5. 새 이미지가 컨테이너 레지스트리에 추가되었는지 확인하세요.
  6. 각 구성 파일을 새 이미지를 가리키도록 업데이트하기 위한 Merge Request를 엽니다. 각 Merge Request에 이미지를 사용하는 작업을 트리거하는 작은 문서 업데이트를 포함하세요.
  7. 각 Merge Request에서 업데이트된 이미지가 테스트에 사용되었는지 확인하세요. (예시 작업 출력)
  8. 각 Merge Request를 기술 작성자에게 할당하여 리뷰하고 머지하세요.

pre-push 훅 구성

Git pre-push 훅을 사용하면 다음을 수행할 수 있습니다:

  • 브랜치를 푸시하기 전에 테스트 또는 기타 프로세스를 실행할 수 있습니다.
  • 이러한 테스트에서 실패하는 경우 브랜치를 푸시를 피할 수 있습니다.

lefthook은 Git 훅 관리자입니다. Git 훅의 구성, 설치 및 제거를 간단하게 만듭니다. 이에 대한 구성은 gitlab 프로젝트의 lefthook.yml 파일에서 사용할 수 있습니다.

문서 린팅에 lefthook을 설정하려면 Pre-push static analysis를 참조하세요.

푸시 시 Vale 오류를 표시하려면 Show Vale warnings on push를 참조하세요.

문서에서 릴린트 비활성화

문서 파일의 일부 린팅은 비활성화할 수 있지만 모든 것을 비활성화할 수는 없습니다:

CI/CD 파이프라인에서 사용되는 도구 버전

린팅 규칙과 최대 호환성을 위해 CI/CD 파이프라인에서 사용되는 linter 버전을 사용해야 합니다.

GitLab 프로젝트에서 사용되는 markdownlint-cli2 및 vale 버전과 일치하는 버전을 사용해야 합니다:

이 두 위치에 설정된 버전은 동일해야 합니다.

도구 버전 명령 추가 정보
markdownlint-cli2 최신 yarn global add markdownlint-cli2 없음.
markdownlint-cli2 특정 yarn global add markdownlint-cli2@0.8.1 @는 특정 버전을 나타내며, 이 예시에서는 도구를 버전 0.8.1로 업데이트합니다.
Vale (asdf 사용) 특정 asdf install 프로젝트의 .tool-versions 파일에 설정된 Vale의 버전을 설치합니다.
Vale (그 외) 특정 해당 없음 직접 다운로드에서 바이너리를 다운로드할 수 있습니다.
Vale (brew 사용) 최신 brew update && brew upgrade vale 이 명령은 macOS 전용입니다.

지원되는 프로젝트

CI/CD 파이프라인에서 각 테스트 실행의 구체적인 내용은 관련 프로젝트의 구성을 참조하십시오:

또한 다음 프로젝트에서 일부 문서 테스트를 실행합니다: