문서 테스트

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

Markdown(.md) 파일의 변경 사항을 포함하는 병합 요청은 다음 CI/CD 작업을 실행합니다.

  • docs-lint markdown: Vale로 문서 내용을 테스트하고, markdownlint로 Markdown 구조를 확인하며, 기타 테스트는 lint-docs.sh에서 실행합니다.
  • docs-lint links: 문서 모음에서 내부 링크의 유효성을 확인합니다.
  • mermaidlint: 문서에서 잘못된 Mermaid 차트를 확인합니다.
  • 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이 있어야 합니다.
  • 표준 이니셜 공백 문자(NBSP, NNBSP, ZWSP)는 문서에서 사용하면 안 됩니다. 왜냐하면 이것들은 검색 색인 및 grepping에서 불규칙성을 유발시킬 수 있기 때문입니다.
  • CHANGELOG.md에 중복된 버전이 포함되어서는 안 됩니다.
  • doc/ 디렉토리에 있는 파일은 실행할 수 없어야 합니다.
  • README.md 대신에 index.md를 사용해야 합니다.
  • 디렉터리와 파일 이름은 대쉬 대신에 밑줄을 사용해야 합니다.
  • 디렉터리와 파일 이름은 소문자여야 합니다.

docs-lint links에서의 테스트

Markdown(.md) 파일의 변경 사항을 포함하는 병합 요청은 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`
  • 소스 파일: 오류를 포함하는 파일의 전체 경로입니다. gitlab 리포지토리에서 파일을 찾으려면 /tmp/gitlab-docs/public/ee를 doc로, .html을 .md로 바꿉니다.
  • 대상: 테스트에서 찾을 수 없는 파일의 전체 경로입니다. gitlab 리포지토리에서 파일을 찾으려면 /tmp/gitlab-docs/public/ee를 doc로, .html을 .md로 바꿉니다.
  • 링크: 스크립트가 찾으려고 시도한 실제 링크입니다.
  • 앵커: 존재하는 경우, 스크립트가 찾으려고 시도한 토픽 제목 앵커입니다.

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

mermaidlint에서의 테스트

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

mermaidlint 작업은 Markdown 파일에 변경 사항이 있는 병합 요청에서 실행됩니다. 스크립트(scripts/lint/check_mermaid.mjs)는 Markdown 파일 중에 Mermaid 구문 오류가 있는 경우 오류를 반환합니다.

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

ui-docs-links lint 작업은 haml-lint를 사용하여 UI 요소(app/views 파일 등)에서의 모든 문서 링크가 유효한 페이지 및 앵커에 링크되는지 확인합니다.

문서 린터 설치

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

로컬에서 문서 테스트 실행

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

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

중요한 점은:

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

로컬에서 Vale 또는 markdownlint 실행

markdownlint 및 Vale의 설치 및 구성 지침이 있습니다.

lint-doc.sh를 로컬에서 실행

Rake 작업을 사용하여 lint-doc.sh 테스트를 로컬에서 실행합니다.

필수 구성요소:

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

  2. 다음을 실행합니다: 

    rake lint:markdown

lint 체크를 실행할 특정 파일 또는 디렉토리를 지정하려면 다음을 실행합니다: 

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

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

=> <user>로 경로 /path/to/gitlab에 있는 문서 린팅 중...
=> cURL 짧은 옵션 확인 중...
=> CHANGELOG.md 중복 항목 확인 중...
=> /path/to/gitlab/doc에서 실행 파일 권한 확인 중...
=> 새로운 README.md 파일 확인 중...
=> markdown 스타일 린팅 중...
=> 논어 린팅 중...
✔ 1개 파일에서 오류 0개, 경고 0개, 제안 0개를 확인했습니다.
✔ 릴팅이 통과되었습니다

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

문서의 링크를 로컬에서 테스트하려면:

  1. gitlab-docs 디렉토리로 이동합니다.

  2. 다음 명령을 실행합니다: 

    # 손상된 내부 링크 확인
bundle exec nanoc check internal_links

# 손상된 외부 링크 확인 (완료에 많은 시간이 소요될 수 있음).
# 이 테스트는 실패해도 되며, gitlab-docs 프로젝트 CI에서만 실행됩니다
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. 변경 요청을 작성하고 기술 작성자에게 리뷰 및 병합을 요청합니다.

린팅 이미지 업데이트

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

의존성의 새 버전(예: 새로운 Ruby 버전)이 출시되면 이미지를 업데이트하여 새 버전을 사용하도록 각 문서 프로젝트의 구성 파일을 업데이트해야 합니다.

린팅 이미지를 업데이트하려면:

  1. gitlab-docs에서 .gitlab-ci.yml을 업데이트하는 변경 요청을 생성합니다. (예시 MR)
  2. 병합되면 매 시간 마다 Build docs.gitlab.com 스케줄된 파이프라인을 시작합니다.
  3. 시작한 파이프라인으로 이동하고 관련 build-images 작업을 수동으로 실행합니다. 예를 들어 image:docs-lint-markdown.
  4. 작업 출력에서 새 이미지 이름을 확인합니다. (예시 작업 출력)
  5. 새 이미지가 컨테이너 레지스트리에 추가되었는지 확인합니다.
  6. 각 구성 파일을 새 이미지를 가리키도록 업데이트하려면 변경 요청을 엽니다.
  7. 각 변경 요청에서 이미지를 사용하는 작업을 트리거하는 작은 문서 업데이트를 포함합니다.
  8. 각 변경 요청에서 업데이트된 이미지가 테스트에 사용되었는지 확인하기 위해 해당하는 작업 출력을 확인합니다. (예시 작업 출력)
  9. 변겨 요청을 기술 작성자에게 할당하여 리뷰하고 병합합니다.

프리푸시 후크 구성

Git pre-push hooks를 사용하면 Git 사용자가 다음을 수행할 수 있습니다:

  • 브랜치를 푸시하기 전에 테스트 또는 기타 프로세스를 실행합니다.
  • 이러한 테스트에서 오류가 발생한 경우 브랜치를 푸시하지 않습니다.

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

문서 린팅을 위해 lefthook을 설정하려면 프리푸시 정적 분석을 참조하세요.

푸시 시 Vale 오류를 표시하려면 푸시 시 Vale 경고 표시를 참조하세요.

문서 린팅 비활성화

문서 파일에서는 일부 문서 릴겅을 비활성화할 수 있지만 모두 비활성화할 수는 없습니다:

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

최대 호환성을 위해 CI/CD 파이프라인에서 사용하는 린팅 규칙과 동일한 도구 버전을 사용하는 것이 좋습니다.

GitLab 프로젝트에서 사용되는 markdownlint-cli(또는 markdownlint-cli2) 및 vale의 버전을 맞추려면 다음을 참조하세요:

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

도구 버전 명령어 추가 정보
markdownlint-cli 최신 yarn global add markdownlint-cli 없음
markdownlint-cli2 최신 yarn global add markdownlint-cli2 없음
markdownlint-cli 특정 yarn global add markdownlint-cli@0.35.0 @은 특정 버전을 나타내며, 이 예제에서 도구가 버전 0.35.0으로 업데이트됨을 나타냅니다.
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 파이프라인에서 각 테스트 실행에 대한 구체적인 정보는 관련 프로젝트의 해당 테스트 구성에서 확인하세요:

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