문서 테스트

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

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

  • docs-lint markdown: 다음을 포함하는 여러 유형의 테스트 실행:
  • docs-lint links: 문서 스위트 내부 링크의 유효성 확인
  • ui-docs-links lint 및 eslint-docs: app/views 파일과 같은 UI 요소에서 링크가 유효한지 확인

lint-doc.sh에 대한 테스트

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

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

Mermaid 차트 검사

Mermaid는 코드로부터 차트와 다이어그램을 작성합니다.

스크립트(scripts/lint/check_mermaid.mjs)는 Markdown 파일에 변경 내용을 포함하는 모든 병합 요청에 대해 lint-doc.sh에서 실행됩니다. 차트에 문제가 있는 경우 스크립트는 오류를 반환합니다.

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

Markdown(.md) 파일에 변경 사항을 포함하는 병합 요청은 다음과 같은 작업을 실행합니다:

이러한 작업은 문제가 있는 링크, 앵커 링크를 확인하고 보고합니다. 네트워크 연결이 필요한 링크는 스킵됩니다.

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

문서 린터 설치

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

로컬에서 문서 테스트 실행

로컬 컴퓨터에서도 변경사항을 미리보거나 문서 테스트를 실행할 수 있습니다. 이렇게 하면 다음과 같은 이점이 있습니다:

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

중요한 점은:

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

로컬에서 Vale, markdownlint 또는 링크 검사 실행

다음에서 설치 및 구성 지침을 확인할 수 있습니다:

로컬에서 lint-doc.sh 실행

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

필수 구성 요소:

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

  2. 다음을 실행하세요: 

    rake lint:markdown

개별 파일이나 디렉토리에 대해 린트 검사를 실행하려면 다음을 실행하세요: 

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개의 제안.
✔ 린팅 통과

Linter 구성 업데이트

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

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

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

  1. 새 브랜치를 생성합니다. 브랜치 이름의 시작이나 끝에 docs-를 추가합니다. 일부 프로젝트에서는 이 규칙을 통해 실행되는 작업을 제한합니다. 

    # markdownlint 구성 파일 복사
cp ../gitlab/.markdownlint-cli2.yaml .
# 기존 Vale 구성을 제거합니다. GitLab 프로젝트에서 일부 규칙이 제거된 경우를 대비하여
rm -r docs/.vale/gitlab
# 'docs' 디렉토리에 문서가 저장된 프로젝트용 gitlab_base Vale 구성 파일 복사
cp -r ../gitlab/doc/.vale/gitlab_base docs/.vale

  2. gitlab-runner, gitlab-omnibus, charts/gitlab, 또는 gitlab-operator를 업데이트하는 경우, gitlab 프로젝트에서도 gitlab-docs Vale 구성을 복사합니다. 예를 들어, 프로젝트의 루트 디렉토리에서 다음을 실행합니다. 

    # 'docs' 디렉토리에 문서가 저장된 프로젝트용 gitlab-docs Vale 구성 파일 복사
cp -r ../gitlab/doc/.vale/gitlab_docs docs/.vale

  3. .markdownlint-cli2.yaml에 대한 생성된 차이를 검토합니다. 예를 들어, 다음을 실행합니다. 

    git diff .markdownlint-cli2.yaml
  4. 필요하지 않은 변경 사항을 제거합니다. 예를 들어, customRules은 gitlab 프로젝트에서만 사용됩니다.

  5. Vale 구성에 대한 생성된 차이를 검토합니다. 예를 들어, 다음을 실행합니다. 

    git diff docs
  6. RelativeLinks.yml에 대한 불필요한 변경 사항을 제거합니다. 이 규칙은 각 프로젝트별로 특정합니다.
  7. .tmpl 파일을 제거합니다. 이러한 파일은 gitlab 프로젝트에서만 사용됩니다.

  8. 새 규칙의 위반 사항을 확인하기 위해 markdownlint-cli2를 실행합니다. 예를 들어: 

    markdownlint-cli2 docs/**/*.md

  9. 새 규칙의 위반 사항을 확인하기 위해 Vale를 실행합니다. 예를 들어: 

    vale --minAlertLevel error docs

  10. 새 브랜치에 대한 변경 사항을 커밋합니다. 일부 프로젝트는 커밋하기 전에 관행적 커밋이 필요하므로 해당 프로젝트의 기여 정보를 확인하세요.

  11. 검토를 위해 병합 요청을 제출합니다.

Linting 이미지 업데이트

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

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

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

  1. gitlab-docs에서 .gitlab-ci.yml을 업데이트하도록 하는 머지 리퀘스트를 엽니다. (예시 MR)
  2. 머지된 후, 새로운 Build docker images manually 스케줄된 파이프라인을 시작합니다.
  3. 시작한 파이프라인으로 이동하여 해당하는 test:image 작업이 완료될 때까지 기다립니다. 예를 들어, test:image:docs-lint-markdown와 같이 테스트 작업:
    • 통과하면 해당하는 image: 작업을 시작합니다. 예를 들어, image:docs-lint-markdown.
    • 실패하면 테스트 작업 로그를 검토하고 문제를 해결하도록 시작합니다. 업데이트된 의존성과 함께 작동하도록 이미지 구성을 수동으로 조정해야할 수 있습니다.
  4. image: 작업이 통과한 후, 새 이미지의 이름을 확인합니다. (예시 작업 출력)
  5. 새 이미지가 컨테이너 레지스트리에 추가되었는지 확인합니다.
  6. 각 구성 파일을 새 이미지를 가리키도록 업데이트하는 머지 리퀘스트를 엽니다. 각 머지 리퀘스트에 이미지를 사용하는 작업을 트리거하기 위한 작은 문서 업데이트가 포함되어야 합니다.
  7. 각 머지 리퀘스트에서 해당하는 작업 출력을 확인하여 업데이트된 이미지가 테스트에 사용되었는지 확인합니다. (예시 작업 출력)
  8. 머지 리퀘스트를 기술 작가에게 할당하여 검토 및 머지합니다.

Pre-push hooks 구성

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

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

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

lefthook을 문서 검토에 사용하려면 Pre-push static analysis를 참조하세요.

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

문서 검토에서 린팅 비활성화

문서 파일에서 일부 린팅을 비활성화할 수 있지만 전체적으로 비활성화할 수는 없습니다:

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

린팅 규칙과 최대한 호환성을 유지하려면 CI/CD 파이프라인에서 사용하는 린터 버전을 사용해야 합니다.

GitLab 프로젝트에서 사용된 markdownlint-cli2 및 vale의 버전을 일치시키려면 다음을 참조하세요:

  • asdf로 관리되는 프로젝트의 경우 프로젝트의 .tool-versions 파일을 참조하세요. 예를 들어, gitlab 프로젝트의 .tool-versions 파일을 참조하세요.
  • CI/CD를 위해 이 도구를 포함하는 image:docs-lint-markdown 도커 이미지를 빌드할 때 사용된 버전(see variables: section)을 참조하세요.

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

도구 버전 명령 추가 정보
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 파이프라인에서 각 테스트 실행의 구체적인 내용에 대한 세부 정보를 알아보려면 해당 프로젝트에서 해당 테스트에 대한 구성을 참조하세요:

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