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

Vale 문서 테스트

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

Vale는 여러 유형의 검사를 확장하는 사용자 정의 테스트를 지원하며, 이를 프로젝트의 문서 디렉터리에 있는 .linting/vale/styles/gitlab 디렉터리에 저장합니다.

일부 Vale 구성 예시:

• 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 확장 프로그램. 플러그인을 구성하여 일부 경고만 표시할 수 있습니다.

• 서브라임 텍스트 SublimeLinter-vale 패키지. 블루이족(blueish)으로 나타나게 하려면 Vale 제안을 SublimeLinter 구성에 추가합니다.

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

• 서브라임 텍스트의 LSP for Sublime Text 패키지 LSP-vale-ls.
• Vim의 ALE 플러그인.
• JetBrains IDE - 플러그인은 없지만 이 이슈 코멘트에 외부 도구를 구성하는 팁이 포함되어 있습니다.

• Emacs Flycheck 확장 프로그램. Vale와 markdownlint에서 오류 린팅을 제공하려면 최소한의 구성이 필요합니다.

  (flycheck-define-checker vale
    "프로즈 체커"
    :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 체커로부터 ‘next’ 체커로 설정됩니다. 이 사용자 정의 Vale 체커를 활성화하면 Vale 및 markdownlint에서 오류 릴팅을 제공합니다.

결과 유형

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

• 오류 - 브랜드 가이드라인, 상표 가이드라인 및 문서 사이트에서 콘텐츠를 잘못 렌더링하는 항목에 대해 표시됩니다.
• 경고 - 일반적인 스타일 가이드 규칙, 원칙 및 모범 사례에 대해 표시됩니다.
• 제안 - 기술 문서 작성 스타일에 대한 개인적인 기호로, 문서를 재구성하거나 예외 디렉터리을 업데이트해야 할 수 있음을 나타냅니다.

결과 유형은 다음과 같은 속성을 갖습니다:

새 Vale 규칙 추가 시기

모든 스타일 가이드 규칙에 Vale 규칙(룰)을 추가하려는 유혹을 떨쳐야 합니다. 그러나 Vale 규칙을 만들고 강제하는 노력과 생성되는 잡음을 염두에 두어야 합니다.

일반적으로 다음 지침을 따릅니다:

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

  한 번에 너무 많은 문제를 수정해야 하는 경우 규칙을 warning 수준으로 추가합니다. 그런 다음 기존 문제를 후속 MR에서 수정합니다. 문제가 수정되면 규칙을 오류로 승격시킵니다.

• 경고 수준 또는 제안 수준 규칙을 추가하는 경우 고려 사항:

  • Vale 출력에 추가되는 경고 또는 제안의 수. 추가 경고 수가 많으면 규칙이 너무 폭넓을 수 있습니다.

  • 저자가 맥락에서 허용할 수 있기 때문에 얼마나 자주 무시할 수 있는지. 규칙이 너무 주관적이면 적절하게 강제할 수 없으며 불필요한 추가 경고를 만듭니다.

  • GitLab UI의 MR 차이에 표시해야 하는지 여부. 규칙을 직접적으로 구현하기 어려운 경우(예를 들어, 페이지 재구성이 필요한 경우) 제안 수준으로 설정하여 로컬 에디터에만 표시합니다.

테스트 실행 제한

파일을 보는 동안 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.OutdatedVersions"' doc/**/*.md

Vale 테스트 비활성화

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

• 특정 규칙을 비활성화하려면 텍스트 앞에 <!-- vale gitlab.rulename = NO --> 태그를 추가하고, 텍스트 뒤에 <!-- vale gitlab.rulename = YES --> 태그를 추가합니다. 이때 rulename을 GitLab styles 디렉터리의 테스트 파일 이름으로 바꿉니다.
• 모든 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 grade level test를 사용하여 문서의 가독성을 결정합니다.

일반적으로 점수가 낮을수록 문서의 가독성이 높습니다. 예를 들어, 변경 후 페이지가 9점인 경우 변경 전에 12점이었다면 가독성이 개선되었음을 의미합니다. 이 점수는 정확한 과학적 기준은 아니지만 페이지의 일반적 복잡성 수준을 나타내는 데 도움을 주기 위한 것입니다.

가독성 점수는 문장 당 단어 수와 단어 당 음절 수에 따라 계산됩니다. 자세한 내용은 Vale 문서를 참조하세요.

Vale 결과를 파일로 내보내기

모든 (또는 필터링된) Vale 결과를 파일로 내보내려면 해당 명령을 수정합니다.

# suggestion, warning 및 error 유형의 결과 반환
find . -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../../results.txt

# warning 및 error 만 반환
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를 위한 Application Support 폴더에 로컬 파일을 만듭니다:

   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에 추가하세요.

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

$ vale --minAlertLevel warning doc/ci/yaml/index.md
 
 doc/ci/yaml/index.md
    ...[snip]...
 3876:17   warning  Instead of future tense 'will   gitlab.FutureTense
                    be', use present tense.
 3897:26   error    Remove 'documentation'          local.new-rule

✖ 1 error, 5 warnings and 0 suggestions in 1 file.

관련 주제

• Vale에서의 스타일
• 예제 스타일을 포함하여 적응할 수 있는 규칙들