• Vale 설치
• 코드 편집기에서 Vale 구성
• 결과 유형
• 새로운 Vale 규칙을 추가하는 시기
• 수행할 테스트를 제한하세요
  • 한 번에 한 규칙만 테스트하기
• Vale 테스트 비활성화
• 푸시 시 Vale 경고 표시
• Vale가 식별하는 문제 해결
  • 철자 테스트
    • 대문자 (약어) 테스트
  • 가독성 점수
• Vale 결과를 파일로 내보내기

Vale 문서 테스트

Vale는 영어 문법, 스타일 및 단어 사용에 대한 린터입니다. Vale의 구성은 프로젝트의 루트 디렉터리에있는 .vale.ini 파일에 저장됩니다.

Vale는 다양한 유형의 확인을 확장하는 사용자 정의 테스트를 지원하며 이러한 테스트는 프로젝트의 문서 디렉터리 중 .linting/vale/styles/gitlab 디렉터리에 저장됩니다.

일부 예시로는 다음과 같습니다:

• gitlab
• gitlab-runner
• omnibus-gitlab
• charts
• gitlab-development-kit

이 구성은 오류 수준 규칙을 강제로 실행하는 빌드 파이프라인에서도 사용됩니다.

Vale를 사용할 수 있습니다:

• 커맨드 라인에서
• 코드 편집기에서
• Git 훅에서. Vale는 Git 훅에서만 오류를 보고하며(동일하게 CI/CD 파이프라인 구성), 제안이나 경고는 보고하지 않습니다.

Vale 설치

vale를 다음 중 하나를 사용하여 설치합니다:

• asdf를 사용하는 경우, asdf-vale 플러그인을 사용합니다. .tool-versions 파일이있는 GitLab 프로젝트의 체크아웃에서(예시) 다음을 실행합니다:

  asdf plugin add vale && asdf install vale
  

• 패키지 관리자를 사용하는 경우:

  • macOS의 경우 brew를 사용하여 실행: brew install vale.
  • Linux의 경우 배포별 패키지 관리자를 사용하거나 릴리스된 바이너리를 사용합니다.

코드 편집기에서 Vale 구성

코드 편집기에서 린터를 사용하는 것이 명령줄에서 명령을 실행하는 것보다 편리합니다.

코드 편집기에서 Vale를 구성하려면 다음 중 하나를 적절하게 설치합니다:

• Visual Studio Code ChrisChinchilla.vale-vscode 익스텐션. 플러그인을 일부 경고만 표시하도록 구성할 수 있습니다.

• Sublime Text의 SublimeLinter-vale 패키지. Vale 제안이 오류가 나타나는 빨간색 대신 파란색으로 나타나게하려면(오류가 나타나는 방식), SublimeLinter 구성에 vale 구성을 추가합니다:

  "vale": {
    "styles": [{
      "mark_style": "outline",
      "scope": "region.bluish",
      "types": ["suggestion"]
    }]
  }
  

• Sublime Text용 LSP 패키지 LSP-vale-ls.
• Vim의 ALE 플러그인.
• JetBrains IDE - 플러그인이 없지만 이 문제 코멘트에 외부 도구를 구성하는 팁이 있습니다.

• Emacs의 Flycheck 익스텐션. Vale와 markdownlint에서 오류 린팅을 제공하도록 커스텀 Vale 린터를 활성화하면 다음과 같이 간단한 구성이됩니다:

  (flycheck-define-checker vale
    "A checker for prose"
    :command ("vale" "--output" "line" "--no-wrap"
              source)
    :standard-input nil
    :error-patterns
      ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message)   line-end))
    :modes (markdown-mode org-mode text-mode)
    :next-checkers ((t . markdown-markdownlint-cli))
  )
    
  (add-to-list 'flycheck-checkers 'vale)
  

  이 설정에서는 정의된 vale 린터의 “다음” 린터로 markdownlint 린터를 설정합니다. 이 사용자 정의 Vale 린터를 활성화하면 Vale와 markdownlint에서 오류 린팅을 활성화합니다.

결과 유형

Vale는 세 가지 유형의 결과를 반환합니다:

• 오류 - 브랜딩 가이드라인, 상표 가이드라인 및 문서 사이트의 콘텐츠가 잘못 렌더링되는 모든 사항에 대해
• 경고 - 일반 스타일 가이드 규칙, 원칙 및 모범 사례에 대해
• 제안 - 기술 문서 스타일 선호도에 대해, 문서를 재구성하거나 예외 디렉터리을 업데이트해야 할 수도 있는 항목에 대해

결과 유형에는 다음과 같은 속성이 있습니다:

새로운 Vale 규칙을 추가하는 시기

모든 스타일 가이드 규칙에 대해 Vale 규칙을 추가하는 것이 유혹적일 수 있습니다. 그러나 Vale 규칙을 만들고 시행하는 데 필요한 노력과 생성되는 잡음을 고려해야 합니다.

일반적으로 다음 지침을 따르세요:

• 오류 수준의 Vale 규칙을 추가하는 경우, 규칙을 추가하기 전에 문서에서 해당 문제의 기존 발생을 해결해야 합니다.

  한 번의 Merge Request에서 수정해야 할 문제가 너무 많은 경우, 해당 규칙을 ‘경고’ 수준으로 추가하세요. 그런 다음, 후속 Merge Request에서 기존 문제를 해결하세요. 문제가 해결되면 규칙을 ‘오류’로 변경하세요.

• 경고 수준이나 제안 수준 규칙을 추가하는 경우 다음 사항을 고려해 보세요:

  • Vale 출력에 추가 경고의 수가 많은지 여부. 추가 경고의 수가 많은 경우 규칙이 너무 폭넓을 수 있습니다.

  • 저자가 상황에 따라 무시할 가능성이 얼마나 되는지. 규칙이 너무 주관적이면 충분히 시행할 수 없으며 불필요한 추가 경고를 만듭니다.

  • GitLab UI의 Merge Request 차이에 표시하는 것이 적합한지 여부. 규칙을 Merge Request에서 직접 구현하기 어려운 경우 (예: 페이지 리팩터링이 필요한 경우) 로컬 편집기에서만 표시되도록 제안 수준으로 설정하세요.

수행할 테스트를 제한하세요

파일 보기 중 Visual Studio Code에 일부 Vale 경고만 표시하도록 설정할 수 있습니다:

1. 기본 설정 > 확장 > Vale로 이동하세요.
2. Vale CLI: 최소 경고 수준을 선택하여 파일에 표시하려는 최소 경고 수준을 설정하세요.

명령줄에서 Vale를 실행할 때 특정 Vale 경고만 표시하려면 --minAlertLevel 플래그를 사용하세요. 이 플래그는 error, warning, 또는 suggestion을 허용하며 필요한 경우 --config와 함께 사용하여 프로젝트의 구성 파일을 가리킬 수 있습니다:

vale --config .vale.ini --minAlertLevel error doc/**/*.md

suggestion 수준의 경고를 포함하여 모든 경고를 표시하려면 플래그를 생략하세요.

한 번에 한 규칙만 테스트하기

명령줄에서 Vale를 실행할 때 한 번에 한 규칙만 테스트하려면 해당 명령을 수정하여 OutdatedVersions를 규칙의 이름으로 바꿔주시면 됩니다:

vale --no-wrap --filter='.Name=="gitlab.OutdatedVersions"' doc/**/*.md

Vale 테스트 비활성화

문서의 일부에 대한 특정 Vale 린팅 규칙 또는 모든 Vale 릴팅 규칙을 비활성화할 수 있습니다:

• 특정 규칙을 비활성화하려면 텍스트 앞에 <!-- vale gitlab.rulename = NO --> 태그를 추가하고,

  텍스트 뒤에 <!-- vale gitlab.rulename = YES --> 태그를 추가하여 rulename을 GitLab styles 디렉터리의 테스트 파일 이름으로 바꿔주시기 바랍니다.

• 모든 Vale 린팅 규칙을 비활성화하려면 텍스트 앞에 <!-- vale off --> 태그를 추가하고,

  텍스트 뒤에 <!-- vale on --> 태그를 추가하십시오.

가능하다면 문제가 되는 규칙과 라인만 제외하십시오.

자세한 정보는 Vale 문서를 참조하세요.

푸시 시 Vale 경고 표시

기본적으로 lefthook은 브랜치로 변경 사항을 푸시할 때 Vale 오류만 표시합니다. 기본 브랜치에는 Vale 오류가 없으므로 여기에 나열된 오류는 브랜치에 커밋으로 인해 도입된 것입니다.

브랜치로 푸시할 때 Vale 경고도 보려면 로컬 환경 변수를 설정하세요: VALE_WARNINGS=true.

푸시 중에 Vale 경고를 표시하여 다음과 같이 문서 스위트를 개선하세요:

• 커밋으로 도입할 수 있는 경고를 감지합니다.
• 기술 부채를 줄이기 위해 해결할 수 있는 페이지에 이미 존재하는 경고를 식별합니다.

이러한 경고는 다음과 같습니다:

• 푸시 동작을 중지시키지 않습니다.
• 파이프라인이 실패하지 않습니다.
• 커밋으로 인해 도입된 경고뿐만 아니라 모든 파일의 경고가 포함됩니다.

푸시 중에 Vale 경고를 표시하려면:

• 자동으로 셸 구성에 VALE_WARNINGS=true를 추가하세요.

• 매뉴얼으로 lefthook 호출 앞에 VALE_WARNINGS=true를 앞에 붙여 사용하세요. 다음과 같이 사용할 수 있습니다:

  VALE_WARNINGS=true bundle exec lefthook run pre-push
  

또한 Vale 경고를 편집기에 표시하도록 편집기를 구성할 수 있습니다.

Vale가 식별하는 문제 해결

철자 테스트

Vale이 유효한 단어를 철자 오류로 표시할 때 다음 가이드를 따라 수정할 수 있습니다:

대문자 (약어) 테스트

Uppercase.yml 테스트는 모든 대문자로 된 단어를 잘못 사용하는지 확인합니다. 예를 들어 이것은 중요하지 않습니다. 같은 사용을 피하세요.

대문자로 된 단어를 사용해야 하는 경우 다음 가이드를 따르세요:

가독성 점수

ReadingLevel.yml에서는 문서의 가독성을 결정하기 위해 Flesch-Kincaid 등급 테스트를 구현했습니다.

일반적인 지침으로, 점수가 낮을수록 문서의 가독성이 높아집니다. 예를 들어, 변경 전에 12점을 얻었고, 변경 후에 9점을 얻었다면 이는 반복적인 가독성 향상을 나타냅니다. 이 점수는 정확한 과학적 기술은 아니지만 페이지의 일반적인 복잡성 수준을 나타내는 데 도움이 되도록 의도되었습니다.

가독성 점수는 문장당 단어 수와 단어당 음절 수를 기반으로 계산됩니다. 자세한 정보는 Vale 문서를 참조하세요.

Vale 결과를 파일로 내보내기

모든 (또는 필터된) Vale 결과를 파일로 내보내려면 이 명령을 수정하세요:

# 제안, 경고 및 오류 유형의 결과 반환
find . -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../../results.txt

# 경고 및 오류만 반환
find . -name '*.md' | sort | xargs vale --minAlertLevel warning --output line > ../../results.txt

# 오류만 반환
find . -name '*.md' | sort | xargs vale --minAlertLevel error --output line > ../../results.txt

이러한 결과는 create_issues.js 스크립트와 함께 사용하여 해커톤과 관련된 문서 작성 작업을 위한 이슈를 생성하는 데 사용할 수 있습니다.