• 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 IDE들 - 해당 플러그인이 없지만 이 이슈 코멘트에 외부 도구를 구성하는 팁이 포함되어 있습니다.

• Emacs용 Flycheck 익스텐션을 사용합니다. Vale과 markdownlint에서 오류 린팅을 제공하도록 최소 구성은 다음과 같습니다:

  (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 규칙을 추가하면 규칙을 추가하기 전에 문서에서 해당 문제의 기존 발생 항목을 수정해야 합니다.

  일부 문제를 하나의 병합 요청에서 수정할 수 없는 경우 규칙을 warning 수준으로 추가하세요. 그런 다음, 이슈를 수정하려면 후속 병합 요청에서 기존 이슈를 수정하세요. 문제가 해결되면 규칙을 error로 변경하세요.

• warning 또는 suggestion 수준의 규칙을 추가하는 경우 고려사항:

  • Vale 출력에서 추가 경고의 수가 많은지 확인하세요. 추가 경고의 수가 많으면 규칙이 너무 폭넓을 수 있습니다.

  • 작성자가 문맥상 허용 가능하기 때문에 무시할 가능성이 얼마나 있는지 확인하세요. 규칙이 주관적이면 적절하게 시행되지 못하고 불필요한 추가 경고를 만듭니다.

  • GitLab UI의 병합 요청 차이에 표시할 것인지 여부를 확인하세요. 규칙이 병합 요청에서 직접 구현하기 어려운 경우(예: 페이지 리팩터링이 필요한 경우) 로컬 편집기에만 표시되도록 suggestion 수준으로 설정하세요.

새로운 Vale 규칙을 추가할 위치

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

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

• gitlab_base: 모든 GitLab 문서에 적용되는 기본 규칙.
• gitlab_docs: https://docs.gitlab.com에 발행된 문서에만 적용되는 규칙.

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

실행할 테스트 제한하기

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

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

명령줄에서 Vale를 실행할 때 특정 Vale 경고만 표시하려면 --minAlertLevel 플래그를 사용하고, 기본적으로 suggestion 수준의 경고를 포함하여 모든 경고를 표시합니다:

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 styles.
• 모든 Vale 릴팅 규칙을 비활성화하려면 텍스트 앞에 <!-- vale off --> 태그를 추가하고 텍스트 뒤에 <!-- vale on --> 태그를 추가하세요.

가능한 경우 문제가 되는 규칙과 줄을 제외하세요.

Vale 규칙에 raw 범위가 있는 경우 무시 선언이 작동하지 않습니다. 자세한 정보는 이 링크를 참조하세요.

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에서는 the Flesch-Kincaid grade level test 를 구현하여 문서의 가독성을 결정합니다.

일반적인 지침으로, 점수가 낮을수록 문서의 가독성이 높아집니다. 예를 들어, 일부 변경 전 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의 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에 원하는 규칙을 추가하세요.

로컬 스타일 디렉토리의 규칙은 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의 스타일
• 적용할 수 있는 규칙이 포함된 예제 스타일