문서 테스트

GitLab 문서는 코드로 처리되는 프로젝트에 저장되며 코드와 같은 방식으로 취급됩니다. 문서의 표준과 품질을 유지하기 위해 코드에 사용되는 것과 유사한 프로세스를 사용합니다.

Markdown (.md) 파일에 대한 변경이 포함된 Merge Request은 다음 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를 사용해야 합니다.
  • 디렉터리와 파일 이름은 대시(-) 대신 밑줄(_)을 사용해야 하며 소문자여야 합니다.

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

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

이러한 테스트에서의 실패는 테스트 결과 Issues found! 영역의 끝에 표시됩니다. 예를 들어, 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 파일에 변경이 포함된 Merge Request에서 실행됩니다. 스크립트(scripts/lint/check_mermaid.mjs)는 Markdown 파일에서 Mermaid 구문 오류가 발생하면 오류를 반환합니다.

Mermaid 차트를 디버그하는 데 도움이 되려면 Mermaid Live Editor를 사용하세요.

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

문서 린터 설치

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

로컬에서 문서 테스트 실행

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

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

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

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

로컬에서 Vale 또는 markdownlint 실행

markdownlint와 Vale의 설치 및 구성 안내가 있습니다.

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

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

필수 사항:

  • 컴퓨터에 필요한 린트 도구가 설치되어 있거나, 이러한 도구가 사전 설치된 이미지를 사용하기 위해 작동하는 Docker 또는 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 프로젝트 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. 새로운 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 후크를 사용하면 Git 사용자가 다음을 수행할 수 있습니다:

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

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

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

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

문서에서 린팅 비활성화

일부 문서 파일에서는 모든 또는 일부 린팅을 비활성화할 수 있습니다.

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 파이프라인에서 각 테스트 실행에 대한 세부 정보는 해당 테스트의 구성을 참조하세요.

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