• Vale 설치
• 편집기에서 Vale 구성
• 결과 유형
• 새로운 Vale 규칙을 추가할 때
• 새로운 Vale 규칙을 어디에 추가할지
• 실행되는 테스트 제한
  • 한 번에 하나의 규칙 테스트
• Vale 테스트 비활성화
• 푸시 시 Vale 경고 표시
• Vale에서 식별한 문제 해결
  • 맞춤법 테스트
    • 대문자(약어) 테스트
  • 가독성 점수
• Vale 결과를 파일로 내보내기
• 로컬에서 사용자 정의 규칙 활성화
• 관련 주제

Vale 문서 테스트

Vale는 영어 문법, 스타일, 단어 사용을 검사하는 린터입니다.

Vale의 설정은 프로젝트의 루트 디렉토리에 위치한 .vale.ini 파일에 저장됩니다.
예를 들어, gitlab 프로젝트의 .vale.ini 파일이 있습니다.

Vale은 문서의 흐름에서 여러 유형의 검사를 확장하는 사용자 정의 규칙을 만드는 것을 지원하며,
이 규칙들은 프로젝트의 문서 디렉토리에 저장됩니다.
예를 들어, gitlab 프로젝트의 doc/.vale 디렉토리가 있습니다.

이 설정은 오류 수준 규칙이 적용되는 빌드 파이프라인에서도 사용됩니다.

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 IDEs - 플러그인이 존재하지 않지만,
  이 문제 댓글에는 외부 도구를 구성하는 팁이 포함되어 있습니다.

• Emacs Flycheck 확장. 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)
  

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

결과 유형

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

• Error - 브랜드 가이드라인, 상표 가이드라인 및 문서 사이트의 콘텐츠가 잘못 렌더링되는 모든 경우에 해당합니다.

• Warning - 일반 스타일 가이드 규칙, 원칙 및 모범 사례에 해당합니다.

• Suggestion - 문서 리팩토링이나 예외 목록 업데이트가 필요할 수 있는 기술 문서 스타일 선호에 해당합니다.

결과 유형은 다음과 같은 속성을 가집니다:

새로운 Vale 규칙을 추가할 때

모든 스타일 가이드 규칙에 Vale 규칙을 추가하고 싶을 유혹이 있을 수 있습니다. 그러나 Vale 규칙을 만들고 시행하는 데 드는 노력과 그로 인한 혼란을 염두에 두어야 합니다.

일반적으로 다음 가이드라인을 따릅니다:

• error-level Vale rule을 추가하는 경우, 규칙을 추가하기 전에 문서에서 기존 문제를 수정해야 합니다.

  한 개의 병합 요청에서 수정하기에 너무 많은 문제가 있는 경우, 규칙을 warning 수준으로 추가합니다. 그런 다음 후속 병합 요청에서 기존 문제를 수정합니다. 문제가 수정되면 규칙을 error로 승격시킵니다.

• warning-level 또는 suggestion-level 규칙을 추가하는 경우 고려해야 할 사항:

  • Vale 출력에서 생성되는 경고 또는 제안이 얼마나 더 많은지. 추가 경고의 수가 상당하다면 규칙이 너무 광범위할 수 있습니다.

  • 저자가 그것을 무시할 가능성이 얼마나 되는지. 맥락에서 받아들여지기 때문에 규칙이 너무 주관적이라면 적절하게 시행할 수 없고 불필요한 추가 경고가 발생할 수 있습니다.

  • GitLab UI에서 병합 요청 diff에 표시되는 것이 적절한지. 병합 요청에서 직접 구현하기 어려운 규칙(예: 페이지 리팩토링이 필요함)이라면 suggestion-level로 설정하여 로컬 편집기에서만 표시되도록 합니다.

새로운 Vale 규칙을 어디에 추가할지

새로운 Vale 규칙은 두 가지 범주 중 하나에 속합니다(Vale에서 styles로 알려짐). 이러한 규칙은 프로젝트의 .vale.ini 파일에 지정된 특정 스타일 디렉토리에 별도로 저장됩니다. 예를 들어, gitlab 프로젝트의 .vale.ini.

새로운 규칙을 추가할 위치는 제안하는 규칙의 유형에 따라 다릅니다:

• gitlab_base: 모든 GitLab 문서에 적용되는 기본 규칙입니다.

• gitlab_docs: https://docs.gitlab.com에 게시된 문서에만 적용되는 규칙입니다.

대부분의 새로운 규칙은 gitlab_base에서 비롯됩니다.

실행되는 테스트 제한

파일을 볼 때 Visual Studio Code가 Vale 경고의 하위 집합만 표시하도록 설정할 수 있습니다:

1. Preferences > Settings > Extensions > Vale로 이동합니다.
2. Vale CLI: Min Alert Level에서 파일에 표시할 최소 경고 수준을 선택합니다.

명령줄에서 Vale를 실행할 때 Vale 경고의 하위 집합만 표시하려면, --minAlertLevel 플래그를 사용하여 error, warning, 또는 suggestion을 수용합니다. 필요에 따라 --config를 조합하여 프로젝트의 구성 파일을 지정할 수 있습니다:

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

플래그를 생략하면 suggestion 레벨 경고를 포함한 모든 경고가 표시됩니다.

한 번에 하나의 규칙 테스트

명령줄에서 Vale를 실행할 때 단일 규칙만 테스트하려면, 이 명령을 수정하여 OutdatedVersions를 규칙 이름으로 대체합니다:

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

Vale 테스트 비활성화

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

• 특정 규칙을 비활성화하려면 텍스트 앞에 <!-- vale gitlab_<type>.rulename = NO --> 태그를 추가하고, 텍스트 뒤에 <!-- vale gitlab_<type>.rulename = YES --> 태그를 추가합니다. rulename은 GitLab 스타일 중 하나의 디렉토리에 있는 테스트의 파일 이름으로 대체합니다.
• 모든 Vale 린팅 규칙을 비활성화하려면 텍스트 앞에 <!-- vale off --> 태그를 추가하고, 텍스트 뒤에 <!-- vale on --> 태그를 추가합니다.

가능한 경우 문제를 일으키는 규칙과 줄만 제외하세요.

무시 문장은 raw 범위의 Vale 규칙에 대해 작동하지 않습니다. 자세한 내용은 이 이슈를 참조하세요.

Vale 범위 규칙에 대한 더 많은 정보를 보려면 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 테스트는 모든 대문자 단어의 잘못된 사용을 확인합니다. 예를 들어, This is NOT important와 같은 사용은 피하세요.

단어가 모든 대문자로 있어야 하는 경우, 다음 지침을 따르세요:

가독성 점수

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 스크립트와 함께 사용할 수 있으며, 해커톤을 위한 문서 관련 이슈를 생성하는 데 사용됩니다.

로컬에서 사용자 정의 규칙 활성화

Vale 3.0 및 이후 버전에서는 규칙을 위한 두 위치를 지원합니다. 이 변경 사항은 프로젝트에 포함된 규칙과 함께 사용자 정의 규칙을 생성하고 사용할 수 있게 해 줍니다.

macOS에서 로컬에서 사용자 정의 규칙을 생성하고 사용하려면:

1. Vale의 응용 프로그램 지원 폴더에 로컬 파일을 만듭니다:

   touch ~/Library/Application\ Support/vale/.vale.ini
   

2. 방금 생성한 .vale.ini 파일에 다음 줄을 추가하세요:

   [*.md]
   BasedOnStyles = local
   

3. ~/Library/Application Support/vale/styles/local 폴더가 존재하지 않으면, 생성하세요:

   mkdir ~/Library/Application\ Support/vale/styles/local
   

4. 원하시는 규칙을 ~/Library/Application Support/vale/styles/local에 추가하세요.

로컬 스타일 디렉토리의 규칙은 Vale 결과에서 gitlab 대신 local로 접두사가 붙습니다. 예:

$ vale --minAlertLevel warning doc/ci/yaml/index.md

 doc/ci/yaml/index.md
    ...[snip]...
 3876:17   warning  미래 시제 'will   gitlab.FutureTense
                    be' 대신 현재 시제를 사용하십시오.
 3897:26   error    'documentation' 제거          local.new-rule

✖ 1 오류, 5 경고 및 0 제안이 1 파일에서 발생했습니다.

관련 주제

• Vale의 스타일

• 조정 가능한 규칙이 포함된 예제 스타일