요약
소개
용어 및 정의
파싱 및 렌더링
목표
구현
- 스크립트
- 명세 파일
워크플로우
- GLFM 명세 업데이트 및 준수 테스트 실행
- 예시 스냅샷 업데이트 및 스냅샷 테스트 실행

GitLab Flavored Markdown (GLFM) 명세 가이드

요약

GitLab Flavored Markdown (GLFM)은 GitHub Flavored Markdown (GFM)을 기반으로 하며, 이는 CommonMark를 기반으로 합니다.
GLFM은 두 개의 “세트”로 구분됩니다:
- “공식 명세“는 특정 구현이나 환경에 의존하지 않으며 어떤 편집기에서든 지원될 수 있습니다.
- “내부 확장“은 GitLab 환경 및 메타데이터에 의존적일 수 있습니다.
이러한 구문 집합의 모든 것은 특별한 Markdown 파일에 의해 지정되며, 이 파일들은 CommonMark 명세 구문을 기반으로 하여 Markdown과 해당 생성된 HTML의 측면에 따라 “예제”를 포함하고 각 예제를 설명하는 연관 문서를 포함합니다.
또한 YAML 메타데이터 파일이 있을 수 있으며, 이는 개별 Markdown/HTML 예제의 처리 및 렌더링 방법에 대한 추가 정보를 포함할 수 있습니다.
이러한 Markdown/YAML 파일과 그들이 포함하는 예제는 여러 목표를 달성합니다:
- GLFM을 렌더링하는 공식 근거지입니다.
- 모든 예제와 관련 문서가 포함된 형식화된 HTML 문서를 렌더링하는 것을 지원하며, GFM 및 CommonMark 명세에서도 지원합니다.
- 공식 명세에 대한 표준 CommonMark 준수 테스트를 지원합니다.
- GitLab 내부 GLFM 처리 논리의 스냅샷 테스트를 지원합니다. 이는 자동으로 생성된 YAML “예제 스냅샷 파일”을 사용하여 GitLab 앱 내에서 자동화된 테스팅을 수행하기 위한 픽스처로 활용됩니다.
위의 목표를 달성하기 위해 다양한 스크립트와 로직이 있습니다.

소개

GitLab은 여러 위치에서 Markdown을 지원합니다. 우리가 사용하는 Markdown 방언은 GitLab Flavored Markdown (GLFM)이라고 합니다.

참고: 이 문서에서 GFM_은 _GitHub Flavored Markdown을 참조합니다. GitLab Flavored Markdown이 아닙니다. 이 문서에서 사용된 다양한 약어에 대한 상세한 설명은 약어 섹션을 참조하세요.

GLFM 방언의 명세는 GitHub Flavored Markdown (GFM) 명세를 기반으로 하며, 이는 CommonMark 명세를 기반으로 합니다. GLFM 명세에는 GFM 명세와 비교했을 때의 많은 추가 내용이 포함되어 있습니다.

이 가이드는 GLFM 명세와 관련된 개발자를 대상으로 하는 문서로서 여러 용어 및 정의, 목표, 도구 및 구현에 대해 설명합니다. GitLab Flavored Markdown을 위한 사용자를 대상으로 하는 문서를 지원하고 보완하기 위한 것입니다.

참고: 이 가이드와 그 내에서 설명된 구현 및 파일은 아직 작업 중입니다. 작업이 진행됨에 따라 이 가이드와 GitLab Flavored Markdown을 위한 사용자 지향 문서 간의 개정과 통합이 가능성이 있습니다.

용어 및 정의

약어: GLFM, GHFM, GFM, CommonMark

GitHub Flavored Markdown은 일반적으로 GFM 약어로 참조되며, 이 문서도 해당 관례를 따릅니다. 이 문서에서는 GitLab Flavored Markdown을 GLFM으로 지칭합니다. 이는 GitHub Flavored Markdown과 구분하기 위함입니다.

유감스럽게도, 이 관례는 아직 이 문서나 GitLab 코드베이스의 다른 부분에서 일관되게 따르지 않고 있습니다. 많은 곳에서 GFM 약어가 GitLab Flavored Markdown을 지칭하는 데 사용됩니다. 이러한 불일치를 해결하기 위한 오픈 이슈가 존재합니다.

코드의 일부 위치에서는 GitHub 및 GitLab 명세를 동시에 참조합니다. 이러한 경우에 GitHub Flavored Markdown은 혼란을 피하기 위해 ghfm_과 같은 변수 또는 상수 이름으로 참조될 수 있습니다. 예를 들어, 우리는 ghfm_spec_v_0.29.md GitHub Flavored Markdown 명세 파일을 위해 ghfm 약어를 사용하며, 이 파일은 gitlab 저장소에 커밋되어 update_specification.rb 스크립트의 입력으로 사용됩니다.

원래의 CommonMark 명세는 CommonMark(약어 없음)로 참조됩니다.

다양한 Markdown 사양

우리가 사용하는 사양 형식은 CommonMark에서 사용된 접근 방식을 기반으로 합니다. 여기서 spec.txt 파일은 설명서로서의 역할 뿐만 아니라 자동 준수 테스트의 입력으로도 사용될 수 있습니다. 이는 CommonMark 사양서에서 설명되어 있습니다:

이 문서는 Markdown 구문을 명확하게 지정하려고 노력합니다. 많은 예제가 Markdown과 HTML을 나란히 보여줍니다. 이러한 예제들은 준수 테스트로 사용될 의도로 제공됩니다.

다음은 사양서의 HTML 렌더링된 버전입니다:

GitLab Flavored Markdown (GLFM) 사양은 다음을 확장합니다:
GitHub Flavored Markdown (GFM) 사양 (소스 spec.txt로부터 렌더링됨)은 다음을 확장합니다:
CommonMark 사양 (소스 spec.txt로부터 렌더링됨)

그러나 GLFM은 GFM 또는 CommonMark보다 복잡한 구문 분석, 렌더링 및 테스트 요구 사항을 가지고 있습니다. 따라서 정적이고 하드코딩되며 수동으로 업데이트되는 spec.txt가 없습니다. 대신, GLFM spec.txt는 다른 입력 파일을 기반으로 자동으로 생성됩니다. 이 프로세스는 아래의 Implementation 섹션에서 자세히 설명됩니다.

참고: 2022년 12월 현재, GitHub Flavored Markdown (GFM) 사양의 HTML 버전은 최신이 아니며 사양의 spec.txt와 일치하지 않습니다. 이 문제에 대한 보고가 cmark-gfm 프로젝트에 등록되었습니다.

공식 사양 vs 내부 확장

GitHub의 GFM과 GitLab의 GLFM은 두 가지 “세트”의 지원하는 Markdown을 가지고 있습니다:

공식 사양
내부 확장

다음 분류도표는 각 사양의 분류 및 용어를 보여줍니다:

graph TD CM[CommonMark - spec.txt - 예: 헤딩] --- GFMS[GFM 사양 - 예: 취소선 확장] GFMS --- GLFM[GLFM 사양 - 예: 색 칩] GFMS --- GFMI[GFM 내부 확장 - 예: GitHub 특정 참조] GLFM --- GLFS[GLFM 내부 확장 - 예: GitLab 특정 참조]

공식 사양

GFM과 GLFM은 각각 공식 사양을 가지고 있으며, 이는 다음을 포함합니다:

CommonMark 표준.
CommonMark 표준에 대한 일반적인 확장.

예를 들어, GFM은 취소선 확장을 추가하고, GLFM은 색 칩 확장을 추가합니다. 이러한 공식 사양의 확장은 특정 구현이나 환경에 의존하지 않습니다. 이러한 확장은 제3자 Markdown 렌더링 엔진에서 구현할 수 있습니다.

내부 확장

GFM과 GLFM은 각각 내부 확장 세트도 가지고 있습니다. 이러한 확장은 GFM 또는 GLFM 공식 사양의 일부가 아니지만 GitHub 또는 GitLab 내부 Markdown 렌더러 및 파서 구현의 일부입니다. 이러한 내부 확장은 종종 GitHub 또는 GitLab 구현이나 환경에 의존하며, 해당 환경과 상호 작용을 통해 사용 가능한 메타데이터에 의존할 수 있습니다. 예를 들어, GitHub는 GitHub 특정 자동 링크 참조를 지원하며, GitLab은 GitLab 특정 참조도 지원합니다. 이러한 내부 확장은 GitHub 또는 GitLab과 통합되는 제3자 Markdown 렌더링 엔진에서도 구현될 수 있습니다. 예를 들어, 편집기나 IDE 플러그인을 통해 사용자가 편집기나 IDE 내에서 이슈, 풀 리퀘스트 또는 병합 요청을 직접 편집할 수 있는 플러그인.

Markdown 예제

사양과 이 안내서의 맥락에서 예제 라는 용어는 특정한 파싱(또는 렌더링) 동작을 나타내기 위해 백틱으로 둘러싼 Markdown + HTML 쌍을 사용하는 관례를 가리킵니다. CommonMark 사양 형식의 Markdown 소스 문자열을 표시하는 것이 목적입니다.

이 맥락에서 RSpec 예제 등과 같은 예제의 기타 유사한 또는 관련된 의미와 헷갈리지 않아야 합니다.

더 자세한 내용은 glfm_official_specification.md 파일 섹션을 참조하세요.

구문 분석기 및 렌더러

명세서가 사용되는 여러 가지 방법과 Markdown 언어와의 관계를 이해하기 위해서는 구문 분석기_와 _렌더러 사이의 차이를 이해하는 것이 중요합니다.

Markdown _구문 분석기_는 Markdown을 입력으로 받아들이고 Markdown 추상 구문 트리(AST)를 출력합니다.
Markdown _렌더러_는 구문 분석기에 의해 생성된 AST를 입력으로 받아 HTML(또는 PDF 또는 다른 관련 렌더링 형식)을 출력합니다.

GLFM 명세서에 의해 주도되는 Markdown 테스트 유형

자동화된 테스트의 두 가지 주요 유형은 GLFM 명세서에 포함된 Markdown 예제 및 데이터에 의해 주도됩니다. 이를 다음과 같이 부릅니다:

Markdown 일치 테스트.
Markdown 스냅샷 테스트.

GitLab 코드베이스에서 많은 다른 유형의 테스트가 발생하며, 이러한 테스트 중 일부는 GLFM Markdown 언어와 관련이 있습니다. 따라서, 이 문서 및 다른 곳에서 이 유형의 명세서에 의존하는 두 가지 테스트에 대해 표준 용어를 사용하여 혼동을 피합니다.

Markdown 일치 테스트

참고: GLFM의 Markdown 일치 테스트는 아직 구현되지 않았습니다.

_Markdown 일치 테스트_는 특정 구현이 CommonMark Markdown 명세에 준수하는지 검증하기 위해 모든 CommonMark Markdown 언어에서 사용되는 표준 테스트 방법을 참조합니다. 이는 주어진 spec.txt 명세와 구현에 대해 표준 CommonMark 도구 spec_tests.py를 실행하여 명세서에 설명된 바에 따라 시행됩니다.

일치 테스트는 GLFM의 공식 명세서 예제에 대해서 만 실행되어야 하며, 내부 확장 예제에는 실행되어서는 안 됩니다. 이는 내부 확장 예제가 GitLab 환경이나 메타데이터에 종속될 수 있지만, 표준 CommonMark 일치 테스트 도구가 이를 지원하지 않기 때문입니다.

참고: spec_tests.py는 최종적으로 Python에 의존성 없이 Ruby로 다시 구현될 수 있습니다.

Markdown 스냅샷 테스트

_Markdown 스냅샷 테스트_는 GitLab 코드베이스에서 수행되는 자동화된 테스트를 지칭하며, 이는 GLFM 명세서의 예제에서 유도되는 example_snapshots fixture 데이터에 의해 주도됩니다. 이는 백엔드 RSpec 테스트 및 프론트엔드 Jest 테스트로 구성되며, 예제 데이터를 사용합니다. 이 fixture 데이터는 YAML 파일에 포함되어 있으며, 명세서의 Markdown 예제 및 기존의 GLFM 구문 분석기 및 렌더러 구현에 의해 생성 및 업데이트됩니다. 또한 불완전한 구현을 테스트하고 상품화하는 데 필요한 경우에는 수동으로 업데이트될 수도 있습니다.

스냅샷 테스트는 모든 예제 - GLFM의 공식 명세서 및 내부 확장 -에 대해 실행되므로, 내부 확장 예제에서 필요한 GitLab 특정 환경 또는 메타데이터를 제공하기 위해 설정 파일을 사용합니다. 이러한 이유로 glfm_example_metadata.yml와 같은 파일을 지원하며, 자세히 검토하여 사용합니다.

스냅샷 테스트의 설계는 사용자가 직면하는 GLFM Markdown의 정확성을 보장하는 데 도움을 줍니다. 이는 백엔드 및 프론트엔드 구문 분석기 및 렌더러를 철저하게 검증함으로써 블랙박스 테스트 방식으로 고찰될 수 있습니다. 이러한 철저한 스타일 때문에 이는 “테스트 피라미드의 꼭대기”에서의 고수준 테스트 유형으로 간주될 수 있습니다.

Markdown 스냅샷 테스트에 사용되는 용어에 관한 용어 설명에 대해서:

Markdown 스냅샷 테스트는 골든 마스터 테스팅 방식의 형태로 간주할 수 있습니다. 이는 승인 테스트 또는 특성 테스트로도 불리기도 합니다.
1. 골든 마스터라는 용어는 기존에 녹음 산업에서 유래되었으며, 모든 사본이 생성되는 최종 믹싱 과정을 참조합니다.
2. 자세한 정보 및 배경은 특성화 테스트 및 골든 마스터에 대해 읽어볼 수 있습니다.
용어 _스냅샷_의 사용은 다른 곳에서 사용되는 Jest 스냅샷 테스트의 접근 방식을 참조하지 않습니다. 그러나 Markdown 스냅샷 테스트는 Jest 스냅샷 테스트처럼 동일한 철학과 패턴을 따릅니다:
1. 스냅샷 예제 fixture 데이터는 소스 컨트롤에 체크되는 파일 형식으로 표현됩니다.
2. 이 파일들은 테스트 대상 코드의 구현을 기반으로 자동으로 생성 및 업데이트될 수 있습니다.
3. 이 파일들은 불완전하거나 버그가 있는 구현을 테스트하는 등 필요에 따라 수동으로 업데이트될 수도 있습니다.
용어 _fixture_의 사용은 표준 Rails 데이터베이스 fixture 파일을 참조하지 않습니다. 대신, 자동화된 테스트를 지원하기 위한 _테스트 픽스처_에 대한 보다 일반적인 정의로 쓰입니다.
이 예제 스냅샷 fixture 파일들은 GLFM 명세서의 다른 부분에서 생성되고 밀접한 관련이 있습니다. 따라서 example_snapshots 디렉토리는 GLFM 명세 파일과 함께 glfm_specification 디렉토리에 공존하도록 설계되었습니다. 실제로 개발자들은 이 파일들을 spec/fixtures 디렉토리로 분할하는 것보다 glfm_specification 디렉토리 하위에 있는 것을 더 단순하고 이해하기 쉽다고 생각했습니다.

Markdown 스냅샷 테스트에서 사용되는 표준화에 관한 섹션도 참조하세요. 이것은 중요한 개념으로 Markdown 스냅샷 테스트에서 사용됩니다.

파싱 및 렌더링

GitLab 애플리케이션에서 사용되는 마크다운 방언은 다음과 같은 두 가지 렌더링 요구사항이 있습니다.

다양한 위치에서 표시될 정적 읽기 전용 HTML 형식으로 렌더링
리치 텍스트 편집기에서 편집 가능한 콘텐츠를 렌더링하는데, “볼 때 그대로 보인다(WYSIWYG)”는 편집기를 지원합니다. 리치 텍스트 편집기는 실시간으로 편집 가능한 마크다운 소스와 WYSIWYG 문서 간에 즉시 전환을 지원합니다.

이러한 요구 사항으로 인해 GitLab에는 두 개의 독립적인 파서 및 렌더러가 있습니다.

백엔드 파서 / 렌더러는 정적 읽기 전용 HTML로 파싱 및 렌더링을 지원합니다. 이것은 루비로 구현되어 있습니다. 이것은 commonmarker gem을 활용하며, 이는 libcmark-gfm의 루비 래퍼입니다. libcmark-gfm은 CommonMark의 참조 파서의 GitHub 포크인 확장된 버전입니다.
프론트엔드 파서 / 렌더러는 리치 텍스트 편집기의 파싱과 WYSIWYG 렌더링을 지원합니다. 이는 자바스크립트로 구현되어 있습니다. 파싱은 Remark 마크다운 파서를 기반으로 하며, MDAST 추상 구문 트리(MDAST)를 생성합니다. 렌더링은 MDAST를 ProseMirror 문서로 변환하는 프로세스입니다. 그런 다음, ProseMirror를 사용하여 ProseMirror 문서를 WYSIWYG HTML로 렌더링합니다. 이 문서에서는 마크다운을 MDAST로 변환하는 과정을 _프론트엔드 / 자바스크립트 파서_로, 그리고 ProseMirror에서 마크다운을 WYSIWYG HTML로 렌더링하는 전체 과정을 _리치 텍스트 편집기_로 지칭합니다. 여러 가지 요구 사항으로 인해 독립적인 프론트엔드 파서 / 렌더러 구현이 필요합니다. 몇 가지 이유는 다음과 같습니다:
1. 백엔드에서 사용되는 HTML 렌더러에 정확한 소스 매핑을 제공하는 데 필요한 지원이 부족합니다.
2. 대역폭과 지연 문제: 사용자가 마크다운 소스와 WYSIWYG 문서 간 전환할 때마다 백엔드로 왕복하는 필요를 제거합니다.
3. WYSIWYG 문서에 대한 다른 HTML 및 브라우저 렌더링 요구 사항. 예를 들어, 편집 가능한 형태로 읽기 전용 요소 표시하기(다이어그램 및 참조와 같은).

렌더링된 HTML의 여러 버전

이러한 GLFM 렌더러 구현(정적 및 WYSIWYG)은 GLFM 공식 사양의 마크다운 예제에 있는 정식 HTML 예제와 다를 수 있는 HTML을 생성합니다. 따라서 GLFM 사양의 모든 마크다운 예제에 대해 예제에서 렌더링될 HTML의 세 가지 버전이 있을 수 있습니다:

정적 HTML
WYSIWYG HTML
정식 HTML

정적 HTML

정적 HTML은 백엔드(Ruby) 렌더러에 의해 생성된 HTML로, 추가적인 스타일 및 동작 HTML이 포함됩니다. 예를 들어, 작업 목록 항목에서 작업을 동적으로 생성하는데 사용되는 작업 생성 버튼이 추가됩니다. GitLab 마크다운 API는 주어진 마크다운 문자열에 대해 이 방법을 사용하여 HTML을 생성합니다.

마크다운 예제에 명시된 마크다운은 glfm_specification/output_example_snapshots/html.yml에서 자동으로 HTML을 생성하는 데 사용되며, update-example-snapshots.rb을 실행할 때 이러한 예제는 마크다운 스냅샷 테스트를 실행할 때 사용됩니다.

WYSIWYG HTML

WYSIWYG HTML은 프론트엔드(JavaScript) 리치 텍스트 편집기에 의해 생성된 HTML로, 파싱과 렌더링 로직이 포함됩니다. 이는 ProseMirror WYSIWYG 편집기에서 편집 가능한 문서를 나타내는 데 사용됩니다.

정적 HTML과 마찬가지로 마크다운 예제에 명시된 마크다운은 glfm_specification/output_example_snapshots/html.yml에서 자동으로 HTML을 생성하는 데 사용되며, update-example-snapshots.rb을 실행할 때 이러한 예제는 마크다운 스냅샷 테스트를 실행할 때 사용됩니다.

정식 HTML

정식 HTML은 마크다운에서 렌더링된 기본적이고 깨끗한 버전의 HTML로, 스타일링 또는 다른 구현에 특정한 클래스/요소가 없습니다.

이 목적은 GLFM spec.txt에 대한 마크다운 준수 테스트를 지원하는 것입니다.

HTML은 항상 하드코딩되어 수동으로 관리되며 절대 자동으로 생성되지 않습니다. 이러한 명시한 마크다운 예제에 대해 다른 파일에 포함되어 있으며, CommonMark, GFM, 그리고 GLFM 공식 사양에 따라 다른 파일에 포함됩니다.

그러나, GLFM 내부 확장에 대한 마크다운 예제에 대해 정식 HTML은 항상 명시되지 않습니다. 이것은 내부 확장이 마크다운 준수 테스트를 통해 테스트되지 않기 때문에 내부 확장 예제에 대한 정식 HTML이 스크립트나 자동화된 테스트에서 사용되지 않기 때문입니다.

정식 HTML 예제의 소스에 대한 자세한 내용은 다음과 같습니다:

CommonMark 사양 및 GFM 확장 사양의 일부인 예제의 경우, 정식 HTML은 GFM spec.txt에서 마크다운 예제 블록을 그대로 복사한 것입니다. 이러한 예제는 GFM spec.txt에서 GLFM 버전의 spec.txt로 그대로 복사되었습니다.
GLFM 공식 사양의 일부인 예제의 경우, 정식 HTML은 glfm_official_specification.md의 예제를 통해 수동으로 유지 및 관리됩니다.
GLFM 내부 확장의 일부인 예제의 경우, 정식 HTML은 항상 명시되지 않으며 모든 예제에 빈 상태로 남겨져야 합니다. 이는 내부 확장 예제에 대해 정식 HTML이 스크립트나 자동화된 테스트에서 사용되지 않기 때문입니다.

정식 HTML은 CommonMark, GFM, 그리고 GLFM 공식 사양의 모든 마크다운 예제에 대해 항상 명시됩니다.

Key Concept: Ensure that the translated text is left-aligned, as per the Markdown format.

HTML의 정규화

백엔드(Ruby) 및 프런트엔드(JavaScript) 렌더러에서 렌더링된 정적 HTML 및 WYSIWYG HTML에는 특정 외형과 동작 요구 사항을 지원하기 위한 추가 스타일링 또는 HTML 요소가 일반적으로 포함되어 있습니다.

백엔드나 프런트엔드 렌더링 로직에서는 정규 HTML에 대한 Markdown 일치 테스트를 실행할 때 필요한 깨끗한 기본 HTML을 직접 렌더링할 수 없습니다. 또한 이것이 가능해서도 안됩니다. 왜냐하면 다음과 같은 이유 때문입니다.

어떤 GitLab 애플리케이션 기능도 직접 지원하는 요구 사항이 아닙니다.
이 기능을 추가함으로써 구현이 더 복잡해지고 불필요한 요구 사항이 생깁니다.

대신, 렌더링된 정적 또는 WYSIWYG HTML은 정규화 과정을 통해 정규 HTML로 변환됩니다. 이 과정을 통해 정적 또는 WYSIWYG HTML의 모든 추가 스타일링 및 동작 HTML이 제거되어 표준 spec.txt 명세의 정규 HTML 예제와 정확히 일치하는 정규 HTML이 생성됩니다.

이 과정에는 canonicalize-html.rb 스크립트를 사용합니다.

정규화

렌더링된 HTML 및 ProseMirror JSON의 버전은 여러 이유로 다를 수 있습니다. 스타일링이나 HTML 구조의 차이뿐만 아니라 속성 또는 노드의 값도 다른 테스트 실행 또는 환경 사이에서 다를 수 있습니다. 예를 들어:

데이터베이스 레코드 식별자
네임스페이스 또는 프로젝트 식별자
URI 일부
파일 경로 또는 이름
랜덤 값

Markdown 스냅샷 테스트가 올바르게 작동하려면 이러한 차이를 고려하여 테스트가 신뢰할 수 있도록 항상 동일한 방식으로 작동하게 해야 합니다.

이러한 차이를 고려하기 위해 정규화 프로세스가 있습니다. 여러가지 정규화 방법이 있습니다.

Fixture 기반 정규화
환경 변수 기반 정규화
정규식 기반 정규화

Fixture 기반 정규화

Fixture 기반 정규화는 가능한 경우에 사용해야 합니다. 왜냐하면 정규식 기반 정규화보다 이해하기 쉽고 간단하기 때문입니다.

Markdown 스냅샷 테스트는 RSpec를 사용하여 예제 스냅샷 파일을 생성합니다. RSpec를 사용하면 다음과 같은 기능을 사용할 수 있습니다.

다른 GitLab RSpec 스위트와 같은 강력한 Fixture 지원과 도우미 기능을 사용할 수 있습니다.
예제 스냅샷을 생성할 때 데이터베이스 상태를 제어하기 위한 Fixture 사용
이 Fixture 설정을 RSpec 공유 컨텍스트로 추출할 수 있습니다. 이 공유 컨텍스트는 예제 스냅샷 테스트가 CI 스위트 또는 run-snapshot-tests.sh를 통해 로컬에서 실행될 때 항상 동일한 데이터베이스 상태를 보장하기 위해 사용됩니다.

이러한 Fixture를 포함하는 RSpec 공유 컨텍스트는 spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb에서 볼 수 있습니다.

환경 변수 기반 정규화

일부 경우에는 변동 값을 제어할 수 없기 때문에 Fixture를 사용할 수 없을 수 있습니다. 이러한 경우에는 환경 변수를 프로덕션 코드에 도입하여 테스트 환경에서 HTML 생성시 변동성을 무력화할 수 있습니다. 프로덕션 코드 경로에서지만 명시적으로 설정되지 않는 한 영향을 미치지 않으므로 무해합니다. 이렇게 함으로써 정규식 기반 정규화를 피할 수 있습니다.

현재 이를 사용하는 예는 일반적으로 무작위인 각주 ID가 GITLAB_TEST_FOOTNOTE_ID로 설정되어 결정론적으로 재정의된 경우입니다. 이는 spec/support/shared_contexts/glfm/example_snapshot_fixtures.rb 공유 컨텍스트에서 Fixture 설정과 함께 설정됩니다.

정규식 기반 정규화

Fixture 기반 또는 환경 변수 기반 정규화 모두 사용할 수 없는 경우 정규식 기반 정규화를 사용합니다. 이 방법은 강력하지만 더 복잡하며 유지 관리가 더 필요합니다. 이 방법은 특정 예제를 이름으로 참조하고 적절한 정규식을 만들어 두 개의 정규화된 버전을 서로 비교하기 위해 사용됩니다.

정규식 기반 정규화를 사용하면 캡처 그룹을 사용하여 HTML 또는 JSON의 두 다른 버전에 적용할 수 있는 사용자 정의 정규식을 적용할 수 있고, 캡처된 그룹의 내용을 동일한 고정 값으로 바꿀 수 있습니다.

그런 다음, 두 정규화된 버전을 서로 비교하여 다른 모든 변수가 동일한지 확인할 수 있습니다.

참고: 여기서 특정 속성 값 확인은 신경 쓰지 않습니다. 따라서 정규화가 이러한 변수 값을 제거하고 고정값으로 바꾸어도 괜찮습니다. 다른 테스트 수준에는 각기 다른 목적이 있습니다.

Markdown 스냅샷 테스트는 렌더링된 HTML/JSON의 구조를 강제하고 이것이 표준 명세를 준수하는지 확인하는 것을 목적으로 합니다.
특정 Markdown 예제의 구현에 대한 개별 단위 테스트는 이러한 변수 값에 대한 특정 및 표적된 테스트를 수행합니다.

마찬가지로 HTML의 정규화에 대해서도 동일한 정규식 캡처 및 대체 정규화 접근 방식을 사용합니다. 정규화된 값 대신 가변 값을 바꾸는 대신 가변되지 않는 HTML의 일부를 제거합니다.

정규화 방법은 glfm_example_normalizations.yml에서 정규화가 어떻게 지정되는지에 대한 자세한 설명을 참조하십시오.

목표

위의 모든 제약 조건을 고려하면 GLFM 사양 및 테스트 인프라와 관련된 여러 목표를 요약할 수 있습니다.

GLFM이 Markdown을 HTML로 렌더링하는 방식에 대한 공식 사양 및 단일 정보 원본이 있어야 합니다. 이러한 정보 원본은 세 개의 Markdown 파일로 나타납니다:
1. GitHub Flavored Markdown 사양(ghfm_spec_v_?.??.md)은 CommonMark + GFM 예제를 위한 것입니다.
2. GLFM 공식 사양(glfm_official_specification.md)은 GLFM의 공식 예제를 위한 것입니다.
3. GLFM 내부 확장(glfm_internal_extensions.md)은 GLFM 내부 확장을 위한 것입니다.
이 공식 사양은 다음 요구 사항을 충족해야 합니다:
1. 해당 사양은 GitHub Flavored Markdown (GFM) 사양의 엄격한 슈퍼셋이어야 합니다. 마치 GitHub Flavored Markdown이 CommonMark 사양의 엄격한 슈퍼셋인 것처럼요.
2. 따라서 이 사양에는 CommonMark 및 GFM에 대한 모든 Markdown 예제, GLFM의 공식 사양 및 내부 확장에 대한 슈퍼셋이 포함되어야 합니다.
3. 이는 GLFM의 공식 사양 및 내부 확장에 포함된 모든 추가 Markdown에 대한 섹션 및 예제를 포함하고, Markdown 예제 및 수반적인 본문과 마찬가지로 표준 형식의 헤더 및 Markdown 예제를 포함해야 합니다.
4. 모든 헤더 및 Markdown 예제는 표준 형식으로 구성되어야 하며, 이는 spec.txt에 포함된 모든 예제를 대상으로 하는 Markdown 준수 테스트를 수행하기 위한 표준 CommonMark 도구인 spec_tests.py에 의해 처리될 수 있어야 합니다.
정적 백엔드(Ruby) 및 WYSIWYG 프론트엔드(JavaScript)를 위한 GLFM 파서 및 HTML 렌더러는 명세에 있는 모든 표준 Markdown + HTML 예제를 일관되게 렌더링해야 합니다. 이는 run-spec-tests.sh에 의해 확인될 수 있습니다.
참고: 여기서의 “일관된”은 두 구현이 동일한 HTML로 렌더링하는 것을 의미하는 것은 아닙니다. 각각은 렌더링하는 데 구현별 추가 사항을 가지고 있기 때문에 렌더링된 HTML은 HTML의 표준화를 거쳐 Markdown 준수 테스트를 실행하기 전에 표준 HTML로 변환되어야 합니다.
정적 백엔드(Ruby)와 WYSIWYG 프론트엔드(JavaScript) 구현 두 가지에 대해 GLFM spec.txt의 모든 Markdown 예제에 해당하는 예제 스냅숏 집합이 YAML 파일 형식으로 존재해야 합니다. 이러한 예제 스냅숏은 다음과 같은 GLFM Markdown 예제에 대한 사용을 지원합니다:
1. 백엔드(Ruby) 파서 및 렌더러가 Markdown을 예상한 사용자 정의 정적 HTML로 변환할 수 있습니다.
2. 프론트엔드(JavaScript) 파서 및 렌더러(여기에는 GitLab 사용자 정의 코드 및 Remark가 포함됨)가 Markdown을 ProseMirror 문서를 나타내는 예상 ProseMirror JSON으로 변환할 수 있습니다.
3. 리치 텍스트 편집기(프론트엔드(JavaScript) 파서 및 렌더러 및 ProseMirror가 포함됨)가 ProseMirror에 의해 렌더링된 예상 사용자 정의 WYSIWYG HTML로 Markdown을 변환할 수 있습니다.
4. 리치 텍스트 편집기는 Markdown에서 MDAST를 거쳐 ProseMirror Document로, 그리고 다시 Markdown으로 변환하는 라운드트립 테스트를 완료할 수 있습니다. 결과적으로 생성된 Markdown이 완전히 동일하며 차이가 없는지 확인합니다.

구현

다음 스크립트 및 파일 세트는 복잡하지만 위에서 나열한 모든 목표를 충족하고 다음과 같은 구현 목표를 주의 깊게 지원하도록 설계되어 있습니다.

GLFM 사양 및 관련 파일의 수동 편집, 선별 및 유지보수 양을 최소화해야 합니다.
상류 CommonMark 사양, GFM 확장 또는 GLFM 확장에 변경 사항이 있는 경우 GLFM 사양 및 관련 파일을 업데이트하는 프로세스를 자동화하고 간소화해야 합니다.
GLFM 사양의 부분적 또는 불완전한 구현을 지원해야 합니다. 이는 진행 중인 작업, 버그 또는 새로운 미래의 Markdown 지원으로 인한 것일 수 있습니다.
표준 CommonMark 준수 테스트와 GLFM 구현 특정 유닛/인수 테스트를 포함한 다양한 테스트를 실행하는 것을 자동화하고 간소화하며 지원해야 합니다.
GLFM 사양 예제에 대한 모든 확장 가능한 메타데이터를 제공하여 자동 수락 테스트 및 자동 문서 업데이트와 같은 현재 및 미래 요구 사항을 지원해야 합니다.

구현에 대한 문서는 세 가지 섹션으로 구분됩니다:

스크립트
사양 파일
예제 스냅숏 파일: 이러한 YAML 파일은 다양한 테스트를 실행하고 결과를 생성하는 데 사용되며 glfm_specification/output_example_snapshots 하위에 위치합니다. 모든 예제 스냅숏 파일은 명세 파일 및 파서 및 렌더러 구현을 기반으로 자동으로 생성됩니다. 그러나 필요한 경우 직접 편집할 수도 있습니다. incompleteness.

스크립트

이 실행 가능한 스크립트는 명세 유지와 테스트 실행과 관련된 다양한 작업을 수행합니다. 각 스크립트에는 scripts/glfm 하위에 위치한 셸 실행 가능한 진입점 파일이 있지만, 실제 구현은 scripts/lib/glfm 하위의 유닛 테스트된 클래스에 있습니다.

참고: 이 스크립트 중 일부는 루비로 구현되어 있고, 다른 일부는 셸 스크립트입니다. 루비 스크립트는 더 복잡한 사용자 정의 스크립트에 사용되어 유닛 테스트와 디버깅을 쉽게 하기 위해 쓰입니다. 셸 스크립트는 다른 셸 하위 프로세스를 실행하는 데 관련된 도전을 피하기 위해 주로 다른 셸 명령을 호출하는 간단한 스크립트에 사용됩니다.

참고: scripts/glfm 하위의 루비 실행 가능 스크립트의 파일 이름에는 밑줄 대신 대시가 들어갑니다. 이러한 명명은 루비 파일에 대한 비표준적이지만, 파일 이름으로 찾을 때 scripts/lib/glfm 하위의 해당 구현 클래스 진입점 파일들과 구별하기 위해 사용됩니다.

`update-specification.rb` 스크립트

scripts/glfm/update-specification.rb 스크립트는 입력 명세 파일을 사용하여 spec.txt 및 spechtml과 함께 출력 명세 파일 및 snapshot_spec.md 및 snapshot_spec.html 출력 예시 스냅샷 파일을 생성하고 업데이트합니다.

백엔드 API에 생성된(또는 업데이트된) 마크다운을 전달하여 HTML로 렌더링하여 HTML 파일이 생성됩니다.

graph LR subgraph 스크립트: S{update-specification.rb} end subgraph 입력 - 마크다운 파일 I1[glfm_official_specification.md - GLFM 공식 명세 예시] --> S end subgraph 출력 - 명세 파일 S --> O1[spec.txt - GLFM 공식 명세 예시] S --> O2[spec.html - GLFM 공식 명세 예시] end

graph LR subgraph 스크립트: S{update-specification.rb} end subgraph 입력 - 마크다운 파일 I1[ghfm_spec_v_0.29.md - CommonMark 및 GHFM 명세 예시] --> S I2[glfm_internal_extensions.md - GLFM 내부 확장 예시] --> S end subgraph 출력 - 예시 스냅샷 파일 S --> O1[snapshot_spec.md - CommonMark, GHFM, GLFM 내부 확장 예시] S --> O2[snapshot_spec.html - CommonMark, GHFM, GLFM 내부 확장 예시] end

`canonicalize-html.rb` 스크립트

scripts/glfm/canonicalize-html.rb은 HTML의 “정규화”를 처리합니다. 이는 추가 HTML을 포함하는 정적 또는 WYSIWYG HTML 문자열을 입력으로 사용하고, 정규 HTML 문자열을 출력하는 파이프-스루 도우미 스크립트입니다.

이는 유닉스 철학에 기반한 독립적이고 모듈적인 단일 기능 스크립트로 구현되어 있습니다. GitLab 렌더러 구현에 대한 마크다운 명세 예시를 정규화된 HTML로 변환하는 CommonMark spec_tests.py 스크립트에 쉽게 사용할 수 있습니다.

`run-spec-tests.sh` 스크립트

scripts/glfm/run-spec-tests.sh는 편리한 셸 스크립트로, 테스트하기 위해 ghfm_spec_v_0.29.md 및 glfm_specification/output_spec/spec.txt 파일들과 함께 scripts/glfm/canonicalize-html.rb 도우미 스크립트를 사용하여 일치 검사 사양을 실행하는 CommonMark 표준 spec_tests.py 스크립트를 실행합니다. 이는 GLFM 렌더러 구현이 마크다운 명세 예시를 정규 HTML로 렌더링하는 지를 테스트합니다.

graph LR subgraph 스크립트: A{run-spec-tests.sh} --> C subgraph 명세 테스트 프로세스 B[canonicalize-html.sh] --> C C[spec_tests.py] end end subgraph 입력 D1[ghfm_spec_v_0.29.md GLFM 명세] --> C D2[spec.txt GLFM 명세] --> C E((GLFM 정적 렌더러 구현)) --> B F((GLFM WYSIWYG 렌더러 구현)) --> B end subgraph "출력: 테스트 결과" C --> G[spec_tests.py 출력] end

`update-example-snapshots.rb` 스크립트

scripts/glfm/update-example-snapshots.rb 스크립트는 예시 스냅샷 YAML 파일을 생성하고 업데이트합니다.

입력은 다음과 같습니다:

glfm_specification/output_spec/snapshot_spec.md 파일, 이 파일은 모든 CommonMark, GFM 및 GLFM 공식 및 내부 예시의 상위 집합을 포함합니다.
glfm_specification/input/gitlab_flavored_markdown/glfm_example_*.yml YAML 파일들, 이는 예시 스냅샷 파일을 생성하기 위한 메타데이터를 포함합니다.

graph LR subgraph 스크립트: A{update-example-snapshots.rb} end subgraph 입력: 마크다운 입력 명세 파일 B1[snapshot_spec.md] --> A C1[glfm_example_status.yml] --> A C2[glfm_example_normalizations.yml] --> A C3[glfm_example_metadata.yml] --> A end subgraph 출력: YAML 예시 스냅샷 파일 A --> E[examples_index.yml] A --> F[markdown.yml] A --> G[html.yml] A --> H[prosemirror_json.yml] end

`run-snapshot-tests.sh` 스크립트

scripts/glfm/run-snapshot-tests.sh 편리한 셸 스크립트는 관련된 모든 Markdown 스냅샷 테스트용 RSpec 및 Jest *_spec 파일(main app spec 폴더의 파일)을 실행합니다. 이것은 example_snapshot YAML 파일에 의해 구동됩니다.

실제 RSpec 및 Jest 테스트 *_spec 파일(프론트엔드 및 백엔드)은 각자의 구현 위치와 일치하는 spec의 해당 위치에 있습니다. 이러한 파일들은 다음과 같이 실행할 수 있습니다. - 기본 파이프라인의 일부로 - 명령줄이나 IDE에서 spec 하위의 다른 파일과 마찬가지로 실행 가능합니다.

그러나 이들은 네 곳에 걸쳐 분산되어 있습니다. - spec/requests 하위의 백엔드 테스트 - ee/spec/requests 하위의 백엔드 EE 테스트 - spec/frontend 하위의 프론트엔드 테스트 - ee/spec/frontend 하위의 프론트엔드 EE 테스트

그러므로 이 편의 스크립트는 로컬 개발에서만 사용되도록 되어 있습니다. 단일 반환 코드를 얻기 위해 한꺼번에 모든 테스트를 실행하는 것을 간소화합니다. 이는 관련 bundle exec rspec ... 및 yarn jest ... 명령에 대한 셸 스크립팅 명령만을 포함합니다.

graph LR subgraph tests: B[관련 rspec+jest 테스트 파일] end subgraph script: A{run-snapshot-tests.sh} -->|호출| B end subgraph "output: 테스트 결과/출력" B --> H[rspec+jest 출력] end subgraph "input: YAML" C[examples_index.yml] --> B D[markdown.yml] --> B E[html.yml] --> B F[prosemirror_json.yml] --> B end

`verify-all-generated-files-are-up-to-date.rb` 스크립트

scripts/glfm/verify-all-generated-files-are-up-to-date.rb 스크립트는 update-specification.rb 스크립트를 실행합니다. update-example-snapshots.rb 스크립트도 실행합니다. 이 스크립트는 생성된 파일과 커밋된 출력 명세 파일 또는 예시 스냅샷 파일에 차이가 있을 경우 예외와 0이 아닌 반환 코드로 실패합니다.

이 스크립트는 glfm-verify CI 작업을 통해 입력 명세 파일의 모든 변경 사항이 생성된 출력 명세 및 예시 스냅샷 파일에 반영되는지 확인합니다.

명세 파일

이 파일들은 GLFM 명세 자체를 나타냅니다. 모두 루트 glfm_specification에 있으며 사용 및 목적에 따라 하위 카테고리로 나뉩니다.

glfm_specification
- input: 자동화된 모든 GLFM 명세 스크립트, 프로세스 또는 테스트를 구동하는 원본 입력 파일이 포함됩니다.
  - github_flavored_markdown: 다운로드된 또는 수동으로 편집된 파일이 들어 있습니다. 이것들은 GLFM 명세와 모든 연관된 예시의 진실의 원천으로 작용합니다.
    - ghfm_spec_v_0.29.md 입력 명세 파일에 대한 공식 최신 GFM spec.txt 사본입니다.
  - gitlab_flavored_markdown: 모든 glfm_* 파일이 들어 있습니다.
    - *.md 입력 명세 파일은 GLFM 명세 및 모든 연관된 예시에 대한 진실의 원천을 나타냅니다.
    - *.yml 입력 명세 구성 파일은 자동화된 GLFM 스크립트 및 프로세스의 여러 측면을 제어합니다.
- output_spec: update-specification.rb 스크립트를 실행하여 자동으로 생성된 spec.txt 및 spec.html 출력 명세 파일이 들어 있습니다.
- output_example_snapshots: 출력 예시 스냅샷 파일이 들어 있습니다. 이 파일들은 스냅샷 테스트를 구동하고, update-specification.rb 스크립트 및 scripts/glfm/update-example-snapshots.rb(=update-example-snapshots.rb) 스크립트를 실행하여 자동으로 생성됩니다.

입력 명세 파일

입력 명세 파일은 명세 자체를 나타내는 수동으로 관리되는 Markdown 파일입니다. 그들은 glfm_specification/input/github_flavored_markdown/*.md와 glfm_specification/input/gitlab_flavored_markdown/*.md에 있습니다.

더 많은 맥락과 세부 정보는 주요 명세 파일 섹션을 참조하십시오.

GitHub Flavored Markdown 명세

ghfm_spec_v_0.29.md은 공식 최신 GFM spec.txt의 사본입니다. - update-specification.rb 스크립트에 의해 자동으로 다운로드되고 업데이트됩니다. - 다운로드될 때 버전 번호가 파일명에 추가됩니다. - 확장자를 *.txt에서 *.md로 변경하여 Markdown 편집기에서 더 잘 처리할 수 있게 합니다.

현재 이 파일은 추가 소개 및 부록 복합 프로필 전용 헤더 섹션만 포함하고 있으며 예시를 포함하지 않습니다.

예시를 포함하는 모든 해더 섹션은 연속적인 파일 섹션에 포함되어야 합니다. 이것은 다음에 의해 구분됩니다: 1. 두 번째 H1 헤더(소개 섹션 이후 첫 번째 헤더)의 시작 1.  HTML 주석 행.

주의: 추가적인 명확성을 위해, 이 파일은 약어 섹션에서 설명된대로 ghfm 약어를 사용하고 있습니다.

`glfm_official_specification.md`

glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification.md은 공식 명세와 해당 문서 및 설명을 수동으로 업데이트한 Markdown+HTML 예제로 구성되어 있습니다.

Markdown 예제는 표준 backtick-delimited spec.txt 형식으로, 각각이 렌더링되어야 하는 Markdown 및 해당하는 정규 HTML을 포함합니다.
모든 GitLab 예제에 대해, 백틱 뒤의 “extension” 주석은 example만 포함해야 합니다. 현재는 GitHub Flavored Markdown 예제와 달리, 구체적인 Markdown을 설명하는 추가적인 확장 주석(예: example strikethrough)은 포함하지 않아야 합니다.
update-specification.rb 스크립트는 이를 생성된 spec.txt의 별첨 부분 이전에 새로운 섹션으로 삽입합니다.
모든 예제가 H1 제목 섹션으로 포함되며, 각각의 예제는 H2 또는 H3 제목 섹션 내에 2단계 또는 3단계로 중첩됩니다.
H3 제목 섹션은 H2 제목 섹션 내에 중첩되어야 합니다. 직접적으로 H1 제목 섹션 내에 중첩될 수 없습니다.

추가적인 글만 포함하는 헤더 섹션도 포함될 수 있습니다.

예제를 포함하는 모든 헤더 섹션은 와  HTML 주석 라인으로 둘러싸인 연속적인 파일 섹션 내에 포함되어야 합니다.

glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification.md 샘플 항목:

# GLFM 공식 명세 예제 섹션

## 강조

### 별표로 감싼 강조

```````````````````````````````` example
**bold**
.
<p><strong>bold</strong></p>
````````````````````````````````

### HTML로 작성한 강조

```````````````````````````````` example
<strong>
bold
</strong>
.
<p><strong>
bold
</strong></p>
````````````````````````````````

`glfm_internal_extensions.md`

glfm_specification/input/gitlab_flavored_markdown/glfm_internal_extensions.md은 GLFM 내부 확장 및 해당 문서 및 설명을 수동으로 업데이트한 Markdown 예제로 구성되어 있습니다.

일반 형식은 glfm_official_specification.md와 동일하며, 표준 backtick-delimited spec.txt 형식으로 Markdown 예제를 포함하는 H1, H2, 또는 H3 섹션으로 이루어져 있습니다.

그러나 정규 HTML 섹션에서 설명한 대로, 각 예제의 HTML 부분은 비어 있으며, 내부 확장 예제는 Markdown 일치 테스트에 사용되지 않으므로 Markdown 부분만 지정됩니다.

추가적인 글만 포함하는 헤더 섹션도 포함될 수 있습니다.

예제를 포함하는 모든 헤더 섹션은 와  HTML 주석 라인으로 둘러싸인 연속적인 파일 섹션 내에 포함되어야 합니다.

glfm_specification/input/gitlab_flavored_markdown/glfm_official_specification.md 샘플 항목:

주의: 이 예제의 모든 줄은 | 문자로 시작합니다. 이 접두사는 markdownlint에 의한 잘못된 오류를 방지하고 다른 Markdown 편집기에서의 잠재적 오류를 방지하기 위해 사용됩니다. 실제 파일에서는 이러한 접두사 | 문자가 없어야 합니다.

|# GLFM 내부 확장 예제 섹션
|
|## 비디오
|
|```````````````````````````````` example
|![video](video.m4v "video title")
|.
|````````````````````````````````

입력 명세 구성 파일

입력 명세 구성 파일은 자동화된 GLFM 스크립트 및 프로세스의 다양한 측면을 제어하는 수동으로 정리된 YAML 파일입니다. 이 파일은 glfm_specification/input/gitlab_flavored_markdown/*.yml에 위치해 있습니다.

더 많은 컨텍스트 및 자세한 내용은 주요 명세 파일 섹션을 참조하세요.

구성 파일 유효성 검사

구성 파일 내의 모든 수동으로 작성된 예제 이름은 자동 생성된 input specification files로부터 생성된 output_example_snapshots/examples_index.yml에서 찾을 수 있는 기존의 Markdown 예제 이름과 일치해야 합니다.

존재하지 않는 예제 이름에 대한 잘못된 참조가 있는 경우, scripts/glfm/update-example-snapshots.rb 스크립트는 구체적인 오류로 실패합니다.

이 유효성 검사에 대한 유일한 예외는 00_로 시작하는 예제 이름입니다. 해당 예제 이름은 YAML 별칭에 대해 예약되어 있습니다. 자세한 내용 및 예제는 glfm_example_normalizations.yml 섹션을 참조하세요.

`glfm_example_status.yml`

glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml은 scripts 및 tests의 동작을 제어합니다.

수동으로 업데이트됩니다.
skip_update_example_snapshot* 필드는 Markdown 예제를 기반으로 한 예제 항목의 자동 생성 상태를 제어합니다.
skip_running_* 제어는 Markdown 일치 테스트 또는 Markdown 스냅샷 테스트가 개별 예제 또는 스냅샷 테스트에서 건너뛰도록 허용합니다.
이는 구현되지 않은, 부분적으로 구현된, 망가진, 생성할 수 없는 경우 또는 어떤 이유로 테스트할 수 없는 다양한 예제의 처리나 테스트를 건너뛸 수 있게 합니다.
모든 항목은 기본적으로 거짓입니다. 이 값을 참으로 평가되는 Ruby 값으로 설정할 수 있습니다. 이는 불리언 true 값이 될 수 있지만, 이상적으로는 예제의 업데이트 또는 테스트가 건너뛰어지는 이유를 설명하는 문자열이어야 합니다.
skip_update_example_snapshot* 항목이 true인 경우 기존 값을 유지합니다. 그러나 YAML이 재작성되므로 문자 값의 스타일과 Block Chomping Indicator (|)가 수정될 수 있습니다. 이는 Ruby psych YAML 라이브러리가 자동으로 결정합니다.

각 예제에 대해 다음과 같은 선택적 항목이 지원됩니다. 모두 기본적으로 false입니다.

skip_update_example_snapshots: 참이면, glfm_specification/output_example_snapshots/html.yml 파일이나 glfm_specification/output_example_snapshots/prosemirror_json.yml 파일의 이 예제 항목에 대한 추가 또는 업데이트를 건너뜁니다. 이 값이 참이면 다른 skip_update_example_snapshot_* 항목이 참이 될 수 없으며, 이 중 하나라도 참이면 오류가 발생합니다.
skip_update_example_snapshot_html_static: 참이면, glfm_specification/output_example_snapshots/html.yml 파일의 이 예제의 정적 HTML 항목을 추가하거나 업데이트하지 않습니다.
skip_update_example_snapshot_html_wysiwyg: 참이면, glfm_specification/output_example_snapshots/html.yml 파일의 이 예제의 WYSIWYG HTML 항목을 추가하거나 업데이트하지 않습니다.
skip_update_example_snapshot_prosemirror_json: 참이면, glfm_specification/output_example_snapshots/prosemirror_json.yml 파일의 이 예제의 항목을 추가하거나 업데이트하지 않습니다.
skip_running_conformance_static_tests: 참이면, 이 예제에 대한 정적 HTML의 Markdown 일치 테스트를 실행하지 않습니다.
skip_running_conformance_wysiwyg_tests: 참이면, 이 예제에 대한 WYSIWYG HTML의 Markdown 일치 테스트를 실행하지 않습니다.
skip_running_snapshot_static_html_tests: 참이면, 이 예제에 대한 정적 HTML의 Markdown 스냅샷 테스트를 실행하지 않습니다.
skip_running_snapshot_wysiwyg_html_tests: 참이면, 이 예제에 대한 WYSIWYG HTML의 Markdown 스냅샷 테스트를 실행하지 않습니다.
skip_running_snapshot_prosemirror_json_tests: 참이면, 이 예제에 대한 ProseMirror JSON의 Markdown 스냅샷 테스트를 실행하지 않습니다.

glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml 샘플 항목:

07_99_00_an_example_with_incomplete_wysiwyg_implementation_1:
  skip_update_example_snapshots: '건너뛰는 이유에 대한 설명.'
  skip_update_example_snapshot_html_static: '건너뛰는 이유에 대한 설명.'
  skip_update_example_snapshot_html_wysiwyg: '건너뛰는 이유에 대한 설명.'
  skip_update_example_snapshot_prosemirror_json: '건너뛰는 이유에 대한 설명.'
  skip_running_conformance_static_tests: '건너뛰는 이유에 대한 설명.'
  skip_running_conformance_wysiwyg_tests: '건너뛰는 이유에 대한 설명.'
  skip_running_snapshot_static_html_tests: '건너뛰는 이유에 대한 설명.'
  skip_running_snapshot_wysiwyg_html_tests: '건너뛰는 이유에 대한 설명.'
  skip_running_snapshot_prosemirror_json_tests: '건너뛰는 이유에 대한 설명.'

`glfm_example_normalizations.yml`

glfm_specification/input/gitlab_flavored_markdown/glfm_example_normalizations.yml은 픽스처 기반 표준화 프로세스를 제어하는 데 사용됩니다. 하나 이상의 regex/replacement 쌍을 Markdown 예제에 지정할 수 있습니다.

수동으로 업데이트됩니다.
예제와 해당 항목 유형에 해당하는 중첩 구조를 갖습니다.
중복을 피하고 여러 예제에서 regex/replacement 쌍을 공유할 수 있도록 하기 위해 YAML 앵커와 별칭을 활발히 사용합니다.
YAML 앵커는 예제의 색인 번호를 기반으로 한 명명 규칙을 사용하여 고유한 앵커 이름을 보장하고 명명 충돌을 피합니다.

참고: fixture-based normalization과 같은 표준화에 대한 다른 접근 방식은 항상 선호됩니다. 다만, fixture-based normalization가 아닌 환경 변수 기반 표준화 등의 접근 방식이 바람직합니다.

glfm_specification/input/gitlab_flavored_markdown/glfm_example_normalizations.yml의 샘플 항목:

# 모든 예제에서 공유되는 모든 YAML 앵커에 주의하십시오.
00_shared:
  00_uri: &00_uri
    - regex: '(href|data-src)(=")(.*?)(test-file\.(png|zip)")'
      replacement: '\1\2URI_PREFIX\4'
01_01_00__section_one__example_containing_a_uri__001:
  html:
    static:
      canonical:
        01_01_00_uri: *00_uri
      snapshot:
        01_01_00_uri: *00_uri
      wysiwyg:
        01_01_00_uri: *00_uri
  prosemirror_json:
    01_01_00_uri: *00_uri
07_01_00__gitlab_specific_markdown__footnotes__001:
  # YAML 앵커는 해당 예에서만 공유되는 경우 해당 예 안에 정의해야 합니다
  shared:
    07_01_00_href: &07_01_00_href
      - regex: '(href)(=")(.+?)(")'
        replacement: '\1\2REF\4'
    07_01_00_id: &07_01_00_id
      - regex: '(id)(=")(.+?)(")'
        replacement: '\1\2ID\4'
  html:
    static:
      canonical:
        07_01_00_href: *07_01_00_href
        07_01_00_id: *07_01_00_id
      snapshot:
        07_01_00_href: *07_01_00_href
        07_01_00_id: *07_01_00_id
      wysiwyg:
        07_01_00_href: *07_01_00_href
        07_01_00_id: *07_01_00_id
  prosemirror_json:
    07_01_00_href: *07_01_00_href
    07_01_00_id: *07_01_00_id

`glfm_example_metadata.yml`

glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml는 스냅샷 예제 생성 프로세스의 다른 측면을 제어합니다.

수동으로 업데이트됩니다.
ee 필드는 예제가 EE 전용인지를 결정합니다. ee 필드가 true인 경우, 예제는 ee/spec/requests/api/markdown_snapshot_spec.rb에서만 실행되며 spec/requests/api/markdown_snapshot_spec.rb에서는 실행되지 않습니다.
api_request_override_path 필드는 지정된 예제의 static HTML을 생성하는 데 사용되는 API 엔드포인트 경로를 재정의합니다. 경우에 따라 다른 엔드포인트는 동일한 경우에도 다른 HTML을 생성할 수 있으므로 동일한 Markdown에 대해 다른 API 엔드포인트를 사용할 수 있어야 합니다. 기본적으로 /markdown 엔드포인트가 사용됩니다.

glfm_specification/input/gitlab_flavored_markdown/glfm_example_metadata.yml의 샘플 항목:

---
08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__001:
  api_request_override_path: /groups/glfm_group/preview_markdown
08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__002:
  api_request_override_path: /glfm_group/glfm_project/preview_markdown
08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__003:
  api_request_override_path: /glfm_group/glfm_project/preview_markdown
08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__004:
  api_request_override_path: /-/snippets/preview_markdown
08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__005:
  api_request_override_path: /glfm_group/glfm_project/-/wikis/new_page/preview_markdown
08_01_00__examples_using_internal_extensions__markdown_preview_api_request_overrides__006:
  ee: true
  api_request_override_path: /groups/glfm_group/-/wikis/new_page/preview_markdown

출력 명세 파일

glfm_specification/output 디렉토리에는 CommonMark 표준 형식인 spec.txt 파일이 포함되어 있습니다. 이는 update-specification.rb 스크립트에 의해 생성된 GLFM 명세를 나타냅니다. 또한 spec.txt를 기반으로 생성된 렌더링된 spec.html도 포함되어 있습니다.

GLFM에서 이러한 출력 파일 spec.*은 input 명세 파일과 동일한 부모 폴더 glfm_specification에 혼합되어 있습니다. 이는 편의상 하나의 위치에 모두 있기 때문입니다. 또한 이 파일들은 수동으로 편집된 파일과 생성된 파일이 혼합되어 있기 때문에 같은 위치에 있습니다.

GFM에서 spec.txt는 테스트 디렉토리에 위치하고, CommonMark에서는 프로젝트 루트에 위치합니다. 표준 위치에 대한 선행 사례가 없습니다. 앞으로 렌더링된 HTML spec.html 버전의 호스팅된 버전을 다른 위치나 사이트로 이동하거나 복사하기로 결정할 수 있습니다.

spec.txt

glfm_specification/output_spec/spec.txt은 표준 형식의 Markdown 명세 파일로, 일반 텍스트와 Markdown + 공식 HTML 예제를 포함하고 있습니다.

GLFM 명세에서 spex.txt에는 glfm_official_specification.md의 공식 명세 예제만 포함되어 있습니다. glfm_internal_extensions.md의 내부 확장 예제는 포함되어 있지 않습니다.

또한 이 파일은 run-spec-tests.sh와 같은 다른 스크립트들의 입력으로 사용됩니다.

이 파일은 update-specification.rb 스크립트에 의해 생성되거나 업데이트되며, 입력 명세 파일(#input-specification-files)을 입력으로 사용합니다. 이 프로세스에 대한 다이어그램과 자세한 내용은 update-specification.rb 스크립트 섹션을 참조하십시오.

참고: spec.txt는 Markdown 파일임에도 불구하고 *.txt 확장자로 명명되어 있습니다. 이는 GFM 및 CommonMark 명세와 일관성을 유지하기 위함입니다. 다른 GLFM Markdown 파일은 Markdown 형식 및 구문 강조 표시를 가능하게 하기 위해 *.md 확장자로 명명됩니다.

spec.html

glfm_specification/output_spec/spec.html은 spec.txt를 기반으로 렌더링된 HTML 파일입니다. 이는 spec.txt와 동시에 update-specification.rb 스크립트에 의해 생성(또는 업데이트)됩니다.

이는 “GitHub Flavored Markdown” (GFM) 명세 및 CommonMark 명세의 HTML 렌더링 버전에 해당하지만, GitLab Flavored Markdown (GLFM) 예제만을 포함하고 있습니다.

참고: 이 HTML의 포맷은 현재 GFM 및 CommonMark HTML 렌더링 명세와 완전히 동일하지 않습니다. 이는 GitLab Markdown 렌더러를 통해 spec.txt를 실행한 결과물일 뿐입니다. HTML을 적절히 포맷하려면 CommonMark 프로젝트의 Lua 스크립트와 템플릿을 복제하거나 재사용해야 합니다: CommonMark Makefile

출력 예제 스냅샷 파일

output_example_snapshots 디렉토리에는 update-specification.rb 및 update-example-snapshots.rb 스크립트에서 생성된 파일들이 포함되어 있습니다. 이는 glfm_specification/input 디렉토리 내의 파일들을 기반으로 생성됩니다.

output-specification.rb 스크립트는 output_snapshot_examples/snapshot_spec.md와 output_snapshot_examples/snapshot_spec.html을 생성합니다. 이 파일들은 입력 파일을 기반으로 생성된 예제를 포함하는 Markdown 명세 파일로, output_spec/spec.txt 및 output_spec/spec.html과 다음과 같은 차이점이 있습니다:

CommonMark, GitHub Flavored Markdown 및 GitLab Flavored Markdown 명세의 모든 예제의 합집합을 포함하고 있습니다. 반면 spec.*는 GLFM 명세만 포함하고 있습니다. 이는 스냅샷 테스트 작업시 모든 예제를 참조할 수 있는 단일한 위치를 제공하기 위함입니다.
예제만을 포함하는 헤더 섹션만 포함하고 있습니다. 예제를 포함하지 않는 본문의 섹션은 포함하고 있지 않습니다.

update-example-snapshots.rb 스크립트는 여러 output_snapshot_examples/*.yml 파일들을 생성합니다. 이 파일들은 스냅샷 테스트를 수행하는 데 사용됩니다.

전체 GLFM 구현이 후반부로 넘어가면 백엔드 (Ruby) 및 프론트엔드 (JavaScript) 모두에 대해 이러한 YAML 파일들은 자동으로 생성됩니다. 그러나 구현이 진행 중인 동안에는 glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml의 skip_update_example_snapshots 키를 사용하여 일부 예제의 자동 생성을 비활성화할 수 있습니다. 대신 구현을 돕기 위해 필요한대로 수동으로 편집할 수 있습니다.

`snapshot_spec.md`

glfm_specification/output_example_snapshots/snapshot_spec.md 는 표준 Markdown + spec.txt(해시태그: #spectxt)와 같은 canonical HTML 예제를 포함하는 Markdown 파일입니다.

update-specification.rb 스크립트를 사용하여 입력 사양 파일을 입력으로 생성하거나 업데이트합니다. 이 프로세스에 대한 다이어그램 및 자세한 설명은 update-specification.rb 스크립트 섹션을 참조하십시오. 또한 update-example-snapshots.rb와 같은 다른 스크립트의 입력으로도 사용됩니다.

다음과 같은 차이점을 가지며 spec.txt와 유사합니다:

spec.txt에는 GitLab Flavored Markdown에 대한 예제만 포함되어 있지만 snapshot_spec.md에는 “GitHub Flavored Markdown” (GFM)specification과 CommonMark specification 명세의 전체 상위 집합 예제도 포함되어 있습니다.
spec.txt는 추가적인 해설적인 서술만 포함하는 추가 header 섹션을 나타내지만, snapshot_spec.md에는 예제만을 포함하는 header 섹션으로 구성되어 있습니다. 이는 이 파일이 다른 output example snapshot files의 입력으로 작동하도록 의도되어 있기 때문에 실제 specification file로 사용되기 위한 것은 아닙니다. spec.txt나 spec.html와 같이.

`snapshot_spec.html`

glfm_specification/output_snapshot_examples/snapshot_spec.html은 snapshot_spec.md를 기반으로 렌더링된 HTML 파일입니다. 이는 snapshot_spec.md를 실행하여 생성(또는 업데이트)됩니다.

참고: 현재 이 HTML의 형식은 GFM 및 CommonMark의 HTML 렌더링 명세와 완전히 동일하지는 않습니다. 이는 GitLab Markdown 렌더러를 통해 생성된 원시 출력만 포함됩니다. 해당 HTML을 올바르게 포맷팅하려면 CommonMark 프로젝트의 Lua 스크립트 및 템플릿을 복제하거나 재사용해야 합니다: CommonMark Makefile

`examples_index.yml`

glfm_specification/output_example_snapshots/examples_index.yml은 모든 CommonMark, GFM 및 GLFM 예제 명을 각각 고유하게 식별하는 이름으로 포함하는 주요 목록입니다.

이는 GFM spec.txt 명세의 계층적 섹션 및 예제에서 생성됩니다.
CommonMark 및 GFM 예제의 경우, 이러한 섹션들은 원래 GFM spec.txt에서 나왔습니다.
GLFM 예제의 경우, 이는 glfm_official_specification.md 및 glfm_internal_extensions.md에서 생성됩니다.
각 예제에 대한 spec_example_position과 같은 추가 메타데이터도 포함되어 있습니다.
1. spec_example_position - 파일에 개별적인 Markdown + HTML5 예제의 색인 순서입니다. 이 값은 파일의 행 번호가 아닌 각 예제의 렌더링된 spec.html 파일에서 예제를 찾는 데 사용될 수 있습니다.
2. source_specification - 예제의 원래 출처 명세: commonmark, github, 또는 gitlab.
예제 항목명 명명 규칙은 중첩 된 헤더 섹션 이름 및 헤더에서 예제 위치에 기반합니다.

`markdown.yml`

glfm_specification/output_example_snapshots/markdown.yml는 glfm_specification/output_example_snapshots/examples_index.yml의 각 항목에 대한 원본 Markdown을 포함합니다.

CommonMark 및 GFM Markdown의 경우 표준 GFM spec.txt를 사용하여 update-example-snapshots.rb 스크립트를 사용하여 생성(또는 업데이트)됩니다.
GLFM의 경우 glfm_official_specification.md 및 glfm_internal_extensions.md 입력 명세 파일에서 생성(또는 업데이트)됩니다.

glfm_specification/output_example_snapshots/markdown.yml 샘플 항목:

06_04_00_inlines_emphasis_and_strong_emphasis_1: |
  *foo bar*

`html.yml`

glfm_specification/output_example_snapshots/html.yml에는 glfm_specification/output_example_snapshots/examples_index.yml의 각 항목에 대한 HTML이 포함되어 있습니다.

세 가지 유형의 항목이 있으며 각각에 대해 다른 HTML이 있습니다:

Canonical
- “Canonical” HTML입니다.
- CommonMark 및 GFM 예제의 경우 HTML은 spec.txt의 예제에서 가져옵니다.
- GLFM 공식 명세 예제의 경우 glfm_official_specification.md에서 생성/업데이트됩니다.
Static
- 이것은 glfm_specification/output_example_snapshots/examples_index.yml의 각 항목에 대한 정적(백엔드(Ruby) 생성) HTML입니다.
- 백엔드 Markdown API에서 생성/업데이트됩니다. (또는 내부 클래스를 통해) update-example-snapshots.rb 스크립트를 통해 수동으로 업데이트될 수 있지만, 구현이 불완전한 정적 예제에 대해 수동으로 업데이트될 수 있습니다.
WYSIWYG
- glfm_specification/output_example_snapshots/examples_index.yml의 각 항목에 대한 WYSIWYG(프론트엔드, JavaScript 생성) HTML입니다.
- 프론트엔드 리치 텍스트 편집기 구현에서 update-example-snapshots.rb 스크립트를 통해 생성(또는 업데이트)됩니다. 구현이 불완전한 WYSIWYG 예제의 경우 수동으로 업데이트될 수 있습니다.

HTML을 생성하는 중에 발생하는 모든 예외 또는 실패는 Error - check implementation 값으로 대체됩니다.

glfm_specification/output_example_snapshots/html.yml 샘플 항목:

06_04_00_inlines_emphasis_and_strong_emphasis_1:
  canonical: |
    <p><em>foo bar</em></p>
  static: |
    <p data-sourcepos="1:1-1:9" dir="auto"><strong>foo bar</strong></p>
  wysiwyg: |
    <p><strong>foo bar</strong></p>

참고: 실제 static 또는 WYSIWYG 항목은 예제 html.yml에 따라 다를 수 있습니다. 구현이 어떻게 발전하는지에 따라 다를 수 있습니다.

`prosemirror_json.yml`

glfm_specification/output_example_snapshots/prosemirror_json.yml에는 glfm_specification/output_example_snapshots/examples_index.yml의 각 항목에 대한 ProseMirror JSON이 포함되어 있습니다.

프론트엔드 코드에서 update-example-snapshots.rb 스크립트를 통해 생성(또는 업데이트)됩니다. 구현이 불완전한 예제의 경우 수동으로 업데이트될 수 있습니다.
생성 중 발생하는 모든 예외 또는 실패는 Error - check implementation 값으로 대체됩니다.

glfm_specification/output_example_snapshots/prosemirror_json.yml 샘플 항목:

06_04_00_inlines_emphasis_and_strong_emphasis_1: |-
  {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "marks": [
              {
                "type": "bold"
              }
            ],
            "text": "foo bar"
          },
        ]
      },
    ]
  }

워크플로우

이 섹션에서는 스크립트를 사용하여 GLFM 명세 및 테스트를 관리하는 방법을 설명합니다.

GLFM 명세 업데이트 및 준수 테스트 실행

update-specification.rb를 실행하여 GLFM 명세를 출력 명세 파일을 업데이트합니다.
출력 명세 파일에 대한 결과적인 변경 사항을 시각적으로 검사하고 확인합니다.
run-spec-tests.sh를 실행합니다. 이 스크립트는 아직 구현되지 않았으며 임시 메시지만 표시됩니다. 구현되면, GLFM 명세를 대상으로 한 준수 테스트를 실행해야 합니다.
출력 명세 파일에 대한 모든 변경 사항을 커밋합니다.

예시 스냅샷 업데이트 및 스냅샷 테스트 실행

현재 진행 중인 기능이나 버그 작업 중인 경우, input specification files를 필요에 따라 수동으로 업데이트하십시오. 이는 다음을 포함할 수 있습니다:
1. Canonical Markdown 또는 HTML 예시인 glfm_official_specification.md 또는 glfm_internal_extensions.md를 업데이트하는 것.
2. glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml을 업데이트하여 예시나 테스트의 현재 상태를 반영하는 것.
update-specification.rb을 실행하여 input specification files에 대한 변경 사항을 반영한 spec.txt를 업데이트하십시오.
output specification files에 대한 결과적인 변경 사항을 시각적으로 검토하고 확인하십시오.
update-example-snapshots.rb을 실행하여 example snapshot files를 업데이트하십시오.
example snapshot files에 대한 결과적인 변경 사항을 시각적으로 검토하고 확인하십시오.
편리한 스크립트로 run-snapshot-tests.sh를 실행하여 예시 스냅샷을 사용하는 모든 관련 프론트엔드(RSpec) 및 백엔드(Jest) 테스트를 실행하십시오.
1. 프론트엔드 또는 백엔드 스냅샷 테스트를 개별적으로 실행할 수도 있습니다.
2. 전형적으로 연속통합 스위트의 일부로 모든 프론트엔드 및 백엔드 테스트도 실행됩니다.
input specification files, output specification files, 또는 example snapshot files에 대한 변경 사항을 커밋하십시오.