문서 테스트

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가 테스트할 수 없는 페이지 내용 문제를 찾습니다.

docs-lint markdown 작업은 이러한 lint-doc.sh 테스트 중 하나라도 실패할 경우 실패합니다:

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

Mermaid 차트 린트

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

스크립트(scripts/lint/check_mermaid.mjs)는 Markdown 파일에 대한 모든 병합 요청에서 lint-doc.sh 체크 중에 실행됩니다. 스크립트는 어떤 Markdown 파일에서라도 Mermaid 구문 오류가 발생하면 오류를 반환합니다.

Mermaid 차트를 디버깅하려면 Mermaid Live Editor를 사용하십시오.

Broken links를 확인하기 위해, 변경된 Markdown(.md) 파일을 포함한 병합 요청은 해당 파이프라인에서 다음 작업을 실행합니다:

이 작업들은 링크, 앵커 링크를 확인하고 문제를 보고합니다. 네트워크 연결이 필요한 링크는 건너뜁니다.

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

문서 린터 설치

문서 스타일 가이드라인을 준수하고 문서에 추가된 내용을 개선하기 위해, 문서 린터를 설치하고 코드 편집기와 통합하세요. 최소한, 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

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

=> /path/to/gitlab에서 <user>로 문서 린트 중...
=> cURL 짧은 옵션 확인 중...
=> CHANGELOG.md 중복 항목 확인 중...
=> /path/to/gitlab/doc의 실행 권한 확인 중...
=> 새로운 README.md 파일 확인 중...
=> 마크다운 스타일 린트 중...
=> 산문 린트 중...
✔ 1개 파일에서 0개의 오류, 0개의 경고 및 0개의 제안.
✔ 린트 통과

린터 구성 업데이트

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

gitlab 프로젝트의 구성은 사실의 근원으로 간주되어야 하며, 모든 업데이트는 먼저 이곳에서 이루어져야 합니다.

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

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

  2. gitlab 프로젝트에서 구성 파일을 복사합니다. 예를 들어, 프로젝트의 루트 디렉터리에서 다음을 실행합니다:

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

  3. 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

  4. .markdownlint-cli2.yaml에 대해 생성된 diff를 검토합니다. 예를 들어, 다음을 실행합니다:

    git diff .markdownlint-cli2.yaml

  5. 필요하지 않은 변경 사항을 제거합니다. 예를 들어, customRules는 오직 gitlab 프로젝트에서만 사용됩니다.

  6. Vale 구성에 대해 생성된 diffs를 검토합니다. 예를 들어, 다음을 실행합니다:

    git diff docs

  7. RelativeLinks.yml에서 불필요한 변경 사항을 제거합니다. 이 규칙은 각 프로젝트에 특정적입니다.

  8. 모든 .tmpl 파일을 제거합니다. 이 파일들은 오직 gitlab 프로젝트에서만 사용됩니다.

  9. 새로운 규칙 위반 여부를 체크하기 위해 markdownlint-cli2를 실행합니다. 예를 들어:

    markdownlint-cli2 docs/**/*.md

  10. 새로운 규칙 위반 여부를 체크하기 위해 Vale를 실행합니다. 예를 들어:

    vale --minAlertLevel error docs

  11. 새 브랜치에 변경 사항을 커밋합니다. 일부 프로젝트에서는 관습적인 커밋을 요구하므로 커밋하기 전에 프로젝트의 기여 정보를 확인하십시오.

  12. 검토를 위한 병합 요청을 제출합니다.

린팅 이미지 업데이트

린트 테스트는 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. 머지 요청을 기술 작가에게 할당하여 검토 및 머지를 요청합니다.

사전 푸시 훅 구성

Git 사전 푸시 훅은 Git 사용자가 다음을 할 수 있도록 합니다:

  • 브랜치를 푸시하기 전에 테스트 또는 기타 프로세스를 실행합니다.

  • 이러한 테스트에서 실패가 발생할 경우 브랜치를 푸시하지 않습니다.

lefthook는 Git 훅 관리 도구입니다. Git 훅을 구성하고 설치하며 제거하는 것을 더 쉽게 만듭니다. 설정은 gitlab 프로젝트의 lefthook.yml 파일에서 사용 가능합니다.

문서 린트를 위해 lefthook를 설정하려면 사전 푸시 정적 분석을 참조하세요.

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

문서에서 린트 비활성화

일부 린트, 그러나 모든 린트를 문서 파일에서 비활성화할 수 있습니다:

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

최대 호환성을 위해 사용 중인 린트 규칙과 동일한 린터 버전을 CI/CD 파이프라인에서 사용해야 합니다.

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 (using asdf) 특정 asdf install 프로젝트의 .tool-versions 파일에 설정된 Vale 버전을 설치합니다.
Vale (기타) 특정 적용할 수 없음. 바이너리는 직접 다운로드할 수 있습니다.
Vale (using brew) 최신 brew update && brew upgrade vale 이 명령은 macOS 전용입니다.

지원되는 프로젝트

CI/CD 파이프라인에서 각 테스트 실행의 세부 정보는 해당 프로젝트의 테스트 구성에서 확인하세요:

우리는 또한 이 프로젝트들에서 몇 가지 문서 테스트를 실행합니다: