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

Vale 문서 테스트

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

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

일부 예시 Vale 구성:

이 구성은 오류 수준 룰 (error-level rules)이 강제되는 빌드 파이프라인에서도 사용됩니다.

Vale을 사용할 수 있는 방법:

명령줄에서 사용
코드 편집기에서 구성
Git 후크에서 사용 (Vale은 Git 후크에서만 오류를 보고하며, 제안이나 경고는 보고하지 않습니다.)

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 제안을 빨간색(오류가 나타나는 색)이 아닌 파란색으로 보이도록 하려면 Vale 구성을 SublimeLinter 구성에 추가하세요:
```
"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는 세 가지 유형의 결과를 반환합니다:

Error - 브랜딩 가이드라인, 상표 가이드라인 및 문서 사이트의 콘텐츠 렌더링에 문제를 일으키는 모든 것에 대해 사용됩니다.
Warning - 일반 스타일 가이드 규칙, 원칙 및 모범 사례에 대해 사용됩니다.
Suggestion - 기술 문서 작성 스타일 기호에 대해 사용되며 문서의 재구성이나 예외 목록의 업데이트가 필요할 수 있습니다.

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

결과 유형	CI/CD 작업 출력에 표시	MR 차이에 표시	CI/CD 작업 실패의 원인	Vale 규칙 링크
`error`	예	예	예	Error-level Vale rules
`warning`	아니요	예	아니요	Warning-level Vale rules
`suggestion`	아니요	아니요	아니요	Suggestion-level Vale rules

새로운 Vale 규칙 추가 시기

매 스타일 가이드 규칙마다 Vale 규칙을 추가하는 것은 유혹적입니다. 그러나, 우리는 Vale 규칙을 만들고 시행하는 노력과 그로 인해 발생하는 노이즈에 유의해야 합니다.

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

만약 error-level Vale 규칙을 추가한다면, 규칙을 추가하기 전에 문서에서 발생하는 문제를 먼저 수정해야 합니다.
하나의 MR에서 수정해야 할 문제가 너무 많다면, 규칙을 warning 수준으로 추가합니다. 그 후 다음 MR에서 문제를 수정합니다. 문제가 해결되면 규칙을 error로 승격시킵니다.
warning-level 또는 suggestion-level 규칙을 추가할 경우, 고려해야 할 사항:
- Vale 출력에 추가되는 경고 또는 제안의 수를 고려합니다. 추가된 경고의 수가 많다면, 규칙이 너무 폭넓을 수도 있습니다.
- 작성자가 맥락상 허용해줄 만한 경고를 얼마나 자주 무시할 수 있는지 고려합니다. 규칙이 너무 주관적이라면 적절히 시행되지 않을 수 있으며 불필요한 추가 경고를 발생시킵니다.
- GitLab UI의 MR 차이에 표시하는 것이 적절한지를 고려합니다. 규칙이 MR에서 직접적으로 구현하기 어려운 경우(예: 페이지 재구성이 필요한 경우) suggestion-level로 설정하여 로컬 편집기에서만 표시합니다.

수행할 테스트 제한

파일을 보는 경우 Visual Studio Code에서 Vale 경고의 하위 집합만 표시하도록 설정할 수 있습니다:

환경 > 설정 > 확장 > Vale로 이동합니다.
Vale CLI: Min Alert Level에서 파일에 표시하고 싶은 최소 경고 수준을 선택합니다.

명령줄에서 Vale를 실행할 때 --minAlertLevel 플래그를 사용하여 error, warning, 또는 suggestion을 받아들이는 최소 경고 수준을 지정하여 하위 집합의 Vale 경고만 표시할 수 있습니다. 필요한 경우 프로젝트에서 구성 파일을 가리키도록 --config와 결합합니다:

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

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

한 번에 하나의 규칙 테스트하기

명령줄에서 Vale를 실행할 때 하나의 규칙만 테스트하려면 이 명령어를 수정하여 OutdatedVersions를 테스트 하려는 규칙의 이름으로 대체하세요:

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

Vale 테스트 비활성화

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

특정 규칙을 비활성화하려면 텍스트 앞에  태그를 추가하고 텍스트 뒤에  태그를 추가합니다. 여기서 rulename을 GitLab styles 디렉터리의 테스트의 파일 이름으로 대체합니다.
모든 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이 유효한 단어를 맞춤법 오류로 표시하는 경우 다음 안내에 따라 수정할 수 있습니다:

표시된 단어	안내
전문용어	해당 문구를 피하도록 문장을 다시 작성합니다.
제품 또는 서비스의 올바르게 대문자로 표기한 이름	해당 단어를 Vale 맞춤법 제외 목록에 추가합니다.
사람 이름	필요하지 않은 경우 이름을 제거하거나 Vale 예외 코드를 인라인으로 추가합니다.
명령어, 변수, 코드 또는 유사한 내용	역따옴표나 코드 블록으로 넣습니다. 예: `The git clone command can be used with the CI_COMMIT_BRANCH variable.` -> The `git clone` command can be used with the `CI_COMMIT_BRANCH` variable.
GitLab의 UI 텍스트	UI와 일치하는지 확인한 후, 다음을 수행합니다: UI와 일치하지 않으면 업데이트합니다. UI가 잘못된 것으로 보이면 이슈를 만들어 UI를 수정해야 하는지 확인합니다. UI와 일치하고 올바른 것으로 보인다면 Vale 맞춤법 제외 목록에 추가합니다.
타사 제품의 UI 텍스트	문구를 피하도록 문장을 다시 작성하거나 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

이러한 결과는 Hackathons을 위한 관련 문서 Issue를 생성하기 위해 create_issues.js 스크립트 와 함께 사용할 수 있습니다.