Vale은 영어의 문법, 스타일, 단어 사용을 검사하는 린터입니다. Vale 구성은 프로젝트 루트 디렉터리에 있는 .vale.ini 파일에 저장됩니다. 예를 들어 gitlab 프로젝트의 .vale.ini가 여기에 해당합니다.

Vale은 여러 유형의 검사를 확장하는 커스텀 규칙 생성을 지원하며, GitLab은 이러한 규칙을 프로젝트의 문서 디렉터리에 저장합니다. 예를 들어 gitlab 프로젝트의 doc/.vale 디렉터리가 여기에 해당합니다.

이 구성은 빌드 파이프라인에서도 사용되며, 파이프라인에서는 오류 수준 규칙이 강제됩니다.

Vale은 다음 환경에서 사용할 수 있습니다.

• 명령줄.
• 코드 에디터.
• Git 훅. Git 훅에서는 (CI/CD 파이프라인과 동일한 구성으로) 오류만 보고하며, 제안이나 경고는 보고하지 않습니다.

Vale 설치#

다음 중 한 가지 방법으로 vale을 설치합니다.

• mise. 예를 들면 다음과 같습니다.

  mise use -g 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"]
    }]
  }
  

• LSP for Sublime Text 패키지 LSP-vale-ls.

• Vim ALE 플러그인.

• JetBrains 플러그인.

• Emacs Flycheck 확장. 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 규칙을 만들고 강제하는 데 드는 노력과 그로 인해 생기는 잡음을 함께 고려해야 합니다.

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

• 오류 수준 Vale 규칙을 추가하려면, 규칙을 추가하기 전에 문서에 이미 존재하는 해당 문제를 모두 수정해야 합니다.

  단일 머지 리퀘스트에서 수정하기에 문제가 너무 많다면 규칙을 warning 수준으로 추가합니다. 그런 다음 후속 머지 리퀘스트에서 기존 문제를 수정합니다. 문제가 모두 해결되면 규칙을 error로 승격합니다.

• 경고 수준이나 제안 수준 규칙을 추가할 때는 다음을 고려합니다.

  • Vale 출력에 경고나 제안이 얼마나 더 늘어나는지 고려합니다. 추가되는 경고 수가 상당하다면 규칙의 범위가 너무 넓을 수 있습니다.

  • 컨텍스트상 허용되는 경우여서 작성자가 얼마나 자주 무시하게 될지 고려합니다. 규칙이 너무 주관적이면 충분히 강제할 수 없고 불필요한 경고만 늘어납니다.

  • GitLab UI의 머지 리퀘스트 diff에 표시하는 것이 적절한지 고려합니다. 머지 리퀘스트에서 직접 반영하기 어려운 규칙이라면(예를 들어 페이지 리팩터링이 필요한 경우) 제안 수준으로 설정해 로컬 에디터에만 표시되도록 합니다.

새 Vale 규칙을 추가하는 위치#

새 Vale 규칙은 두 범주(Vale에서는 스타일이라고 부릅니다) 중 하나에 속합니다. 이 규칙은 프로젝트의 .vale.ini 파일에 지정된 각 스타일 디렉터리에 따로 저장됩니다. 예를 들어 gitlab 프로젝트의 .vale.ini가 여기에 해당합니다.

새 규칙을 어디에 추가할지는 제안하려는 규칙의 유형에 따라 달라집니다.

• gitlab_base: 모든 GitLab 문서에 적용되는 기본 규칙입니다.
• gitlab_docs: https://docs.gitlab.com에 게시되는 문서에만 적용되는 규칙입니다.

대부분의 새 규칙은 gitlab_base에 속합니다.

실행할 테스트 제한#

파일을 볼 때 Vale 경고의 일부만 표시하도록 Visual Studio Code를 설정할 수 있습니다.

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

명령줄에서 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 --> 태그를 추가합니다.

가능하면 문제가 되는 규칙과 행만 제외합니다.

Vale 범위 지정 규칙에 대한 자세한 내용은 Vale 문서를 참고합니다.

raw 범위를 사용하는 Vale 규칙을 비활성화하는 임시 해결 방법#

일반적으로 raw 범위를 사용하는 Vale 규칙은 비활성화할 수 없습니다.

다만 변경 때문에 거짓 양성으로 Vale 이 실패하는 경우, 변경 부분 주변의 서식을 조정해 문제를 우회할 수 있을 때가 있습니다. 예를 들어 거짓 양성이 발생한 행의 시작 부분에 공백을 조금 더 추가할 수 있습니다. 이때 페이지가 정상적으로 렌더링되는지 반드시 확인하고, 특수한 서식을 사용한 이유를 설명하는 HTML 주석을 추가합니다.

예를 들면 다음과 같습니다(실제 예시에서 가져왔습니다).

<!--
The following codeblock uses extra spaces to avoid the Vale ReferenceLinks test.
Do not remove the two-space nesting.
-->

  - [Use a reference-style link that's normally prohibited][1]

  [1]: https://example.com/

자세한 내용은 이 Vale 이슈를 참고합니다.

커밋 또는 푸시 시 Vale 경고 표시#

기본적으로 Lefthook의 Vale 검사는 오류 수준 문제만 표시합니다. 기본 브랜치에는 Vale 오류가 없으므로, 여기에 표시되는 오류는 해당 브랜치에 대한 커밋에서 새로 생긴 것입니다.

Vale 경고도 함께 보려면 로컬 환경 변수 VALE_WARNINGS=true를 설정합니다.

커밋이나 푸시 시 Vale 경고를 활성화하면 다음과 같은 방식으로 문서 모음을 개선할 수 있습니다.

• 커밋으로 새로 유입될 수 있는 경고를 탐지합니다.
• 페이지에 이미 존재하는 경고를 확인하고 해결해 기술 부채를 줄입니다.

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

• 커밋 동작을 막지 않습니다.
• 파이프라인을 실패시키지 않습니다.
• 커밋으로 새로 생긴 경고뿐 아니라 파일의 모든 경고를 포함합니다.

Lefthook에서 Vale 경고를 활성화하는 방법은 다음과 같습니다.

• 자동으로 적용하려면 셸 구성에 VALE_WARNINGS=true를 추가합니다.

• 수동으로 적용하려면 lefthook 호출 앞에 VALE_WARNINGS=true를 붙입니다. 예를 들면 다음과 같습니다.

  VALE_WARNINGS=true bundle exec lefthook run pre-commit
  

Vale 경고를 표시하도록 에디터를 구성할 수도 있습니다.

Vale 이 식별한 문제 해결#

철자 테스트#

Vale 이 올바른 단어를 철자 오류로 표시하는 경우, 다음 지침에 따라 수정할 수 있습니다.

대문자(약어) 테스트#

Uppercase.yml 테스트는 모두 대문자로 쓴 단어의 잘못된 사용을 검사합니다. 예를 들어 This is NOT important 같은 사용을 피합니다.

단어를 반드시 모두 대문자로 써야 한다면 다음 지침을 따릅니다.

가독성 점수#

ReadingLevel.yml에는 문서의 가독성을 판단하기 위해 Flesch-Kincaid 학년 수준 테스트를 구현해 두었습니다.

일반적인 지침으로, 점수가 낮을수록 문서를 읽기 쉽습니다. 예를 들어 변경 전에 12 점이던 페이지가 변경 후 9 점이 되었다면 가독성이 점진적으로 개선된 것입니다. 이 점수는 엄밀한 지표는 아니지만, 페이지의 전반적인 복잡도를 가늠하는 데 도움이 됩니다.

가독성 점수는 문장당 단어 수와 단어당 음절 수를 기준으로 계산됩니다. 자세한 내용은 Vale 문서를 참고합니다.

Vale 결과를 파일로 내보내기#

전체 Vale 결과나 필터링된 결과를 파일로 내보내려면 다음 명령을 수정해 사용합니다.

# Returns results of types suggestion, warning, and error
find . -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../../results.txt

# Returns only warnings and errors
find . -name '*.md' | sort | xargs vale --minAlertLevel warning --output line > ../../results.txt

# Returns only errors
find . -name '*.md' | sort | xargs vale --minAlertLevel error --output line > ../../results.txt

이 결과는 해커톤용 문서 관련 이슈를 생성하는 데 사용할 수 있습니다.

로컬에서 커스텀 규칙 활성화#

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.

관련 주제#

• Styles in Vale
• 예시 스타일. 참고해 활용할 수 있는 규칙이 담겨 있습니다