InfoGrab DocsInfoGrab Docs

Rapid Diffs 가이드라인

요약

이 가이드라인은 Rapid Diffs의 모든 변경에 적용됩니다. 코드를 작성하기 전에 설계 원칙을 검토합니다. 서버가 프래그먼트를 캐시하고 재사용할 수 있도록, 각 <diff-file> 프래그먼트는 같은 diff를 보는 모든 사용자에게 동일한 HTML을 생성해야 합니다.

이 가이드라인은 Rapid Diffs의 모든 변경에 적용됩니다. 아키텍처와 기능 추가 방법은 Rapid Diffs를 참고합니다.

코드를 작성하기 전에 설계 원칙을 검토합니다.

캐싱#

서버가 프래그먼트를 캐시하고 재사용할 수 있도록, 각 <diff-file> 프래그먼트는 같은 diff를 보는 모든 사용자에게 동일한 HTML을 생성해야 합니다.

  • DiffFileComponent, 뷰어, 헤더와 같은 diff 파일 컴포넌트는 diff 콘텐츠에만 의존해야 합니다. 콘텐츠 SHA, 파일 경로, 줄 내용, 줄 번호, 뷰어 이름이 해당합니다.
  • 권한, 환경설정, 아바타 URL과 같은 사용자별 데이터는 개별 diff 파일 안이 아니라 루트 요소의 data-app-data에 둡니다.
  • CSRF 토큰이나 세션 상태와 같은 요청별 데이터를 diff 파일 HTML에 포함하지 않습니다.
  • 기능이 diff 파일 안에 사용자별 콘텐츠(예: 토론 스레드)를 필요로 하면, 마운트 후 클라이언트에서 콘텐츠를 로드합니다.
  • ViewComponent에 속성을 추가할 때 값이 사용자마다 달라지는지 확인합니다. 값이 달라진다면 해당 속성은 diff 파일 템플릿에 속하지 않습니다.

클라이언트와 서버 분리#

  • 같은 diff를 보는 모든 사용자에게 기능이 같은 HTML을 생성한다면 서버에서 렌더링합니다. 예를 들어 구문 강조된 코드 줄, hunk 헤더, 파일 헤더는 서버에서 렌더링합니다. 기능이 사용자 입력에 반응하거나 사용자마다 다르다면 어댑터를 통해 클라이언트에서 처리합니다. 예를 들어 인라인 토론, 파일 접기 토글, 옵션 메뉴, 줄 퍼머링크 재작성은 클라이언트 측입니다.
  • 전역 구성은 data-app-data에, 파일별 메타데이터는 data-file-data에, 작은 요소별 값은 개별 data-* 속성에 둡니다. 전체 참조는 클라이언트로의 데이터 흐름을 참고합니다.
  • 내비게이션과 첫 번째로 보이는 diff 사이에 지연을 추가하지 않습니다. 변경이 크리티컬 패스에 비용을 추가한다면 그 비용을 미루거나 없앱니다.

HTML과 스타일#

  • diff 파일 템플릿 안에서 Tailwind 유틸리티 클래스를 사용하지 않습니다. Tailwind 클래스를 쓴 diff 줄 하나는 짧은 rd- 클래스 이름을 쓴 줄보다 3~5배 커질 수 있습니다. 수천 줄에 걸치면 이 차이는 상당합니다.
  • diff 파일 본문 안에 JSON blob을 포함하지 않습니다. 한 번만 구문 분석되는 <diff-file> 요소의 data-file-data를 사용하고, 작은 값에는 특정 요소의 data-* 속성을 사용합니다.
  • 깊게 중첩된 래퍼 요소를 피합니다. 수천 줄에 걸쳐 곱해지는 추가 <div> 하나하나가 구문 분석 시간과 메모리에 측정 가능한 오버헤드를 더합니다.
  • 레거시 스타일과 충돌하지 않도록 모든 CSS 클래스에 rd- 접두사를 붙입니다.
  • 인라인 스타일을 피합니다. 스타일은 SCSS 페이지 번들에 정의합니다.
  • 깊게 중첩된 선택자를 피합니다. 한 단계 클래스 정의를 선호합니다.
  • 고정 헤더와 사이드바 너비와 같은 페이지별 오프셋에는 CSS 변수를 사용합니다. 컴포넌트 스타일이 아니라 페이지 번들에 정의합니다.

어댑터와 런타임#

  • 개별 요소에 리스너를 연결하지 않습니다. 위임된 clicks 핸들러나 어댑터 수명 주기 이벤트를 사용합니다.
  • 필수가 아닌 작업은 크리티컬 렌더링 경로 이후로 미룹니다. 파일이 표시된 후 적용되는 작업에는 VISIBLE/INVISIBLE 핸들러를 사용합니다.
  • 복잡한 컴포넌트는 미리 마운트하지 말고 첫 사용자 상호작용 시점에 마운트합니다.
  • 중간 상태는 클로저가 아니라 this.sink에 저장합니다. 큰 DOM 참조를 캡처하는 클로저는 메모리 누수를 일으킵니다.
  • 모든 이벤트 리스너와 DOM 참조를 onUnmounted에서 정리합니다. Pinia 스토어나 Vue 컴포넌트처럼 어댑터 밖에 DOM 참조를 저장한다면, 해당 참조도 onUnmounted에서 지웁니다. 그렇게 하지 않으면 분리된 DOM 트리가 메모리에 남습니다.
[MOUNTED](onUnmounted) {
  const handler = () => { /* ... */ };
  this.diffElement.addEventListener('input', handler);
  onUnmounted(() => {
    this.diffElement.removeEventListener('input', handler);
  });
},

접근성#

Rapid Diffs는 WCAG 2.1 및 ATAG 2.0 지침의 AA 수준을 준수해야 합니다.

  • 이미지와 같은 텍스트가 아닌 diff 콘텐츠에는 텍스트 대안을 제공합니다.
  • 모든 상호작용 요소를 키보드로 조작할 수 있게 합니다. 파일 토글, 펼치기 컨트롤, 토론 스레드, 옵션 메뉴는 마우스를 요구하지 않아야 합니다.
  • 보조 기술 사용자가 파일, hunk, 토론 사이를 이동할 수 있도록 시맨틱 HTML과 적절한 제목 계층 구조를 사용합니다.
  • 보기 모드, 공백 설정, 파일 브라우저 표시 여부와 같은 사용자 환경설정을 세션 간에 유지합니다.
  • Pajamas 접근성 개발자 체크리스트를 따릅니다.

Rapid Diffs 가이드라인

GitLab v19.6
원문 보기

요약

이 가이드라인은 Rapid Diffs의 모든 변경에 적용됩니다. 코드를 작성하기 전에 설계 원칙을 검토합니다. 서버가 프래그먼트를 캐시하고 재사용할 수 있도록, 각 &#x3C;diff-file> 프래그먼트는 같은 diff를 보는 모든 사용자에게 동일한 HTML을 생성해야 합니다.

이 가이드라인은 Rapid Diffs의 모든 변경에 적용됩니다. 아키텍처와 기능 추가 방법은 Rapid Diffs를 참고합니다.

코드를 작성하기 전에 설계 원칙을 검토합니다.

캐싱#

서버가 프래그먼트를 캐시하고 재사용할 수 있도록, 각 <diff-file> 프래그먼트는 같은 diff를 보는 모든 사용자에게 동일한 HTML을 생성해야 합니다.

  • DiffFileComponent, 뷰어, 헤더와 같은 diff 파일 컴포넌트는 diff 콘텐츠에만 의존해야 합니다. 콘텐츠 SHA, 파일 경로, 줄 내용, 줄 번호, 뷰어 이름이 해당합니다.
  • 권한, 환경설정, 아바타 URL과 같은 사용자별 데이터는 개별 diff 파일 안이 아니라 루트 요소의 data-app-data에 둡니다.
  • CSRF 토큰이나 세션 상태와 같은 요청별 데이터를 diff 파일 HTML에 포함하지 않습니다.
  • 기능이 diff 파일 안에 사용자별 콘텐츠(예: 토론 스레드)를 필요로 하면, 마운트 후 클라이언트에서 콘텐츠를 로드합니다.
  • ViewComponent에 속성을 추가할 때 값이 사용자마다 달라지는지 확인합니다. 값이 달라진다면 해당 속성은 diff 파일 템플릿에 속하지 않습니다.

클라이언트와 서버 분리#

  • 같은 diff를 보는 모든 사용자에게 기능이 같은 HTML을 생성한다면 서버에서 렌더링합니다. 예를 들어 구문 강조된 코드 줄, hunk 헤더, 파일 헤더는 서버에서 렌더링합니다. 기능이 사용자 입력에 반응하거나 사용자마다 다르다면 어댑터를 통해 클라이언트에서 처리합니다. 예를 들어 인라인 토론, 파일 접기 토글, 옵션 메뉴, 줄 퍼머링크 재작성은 클라이언트 측입니다.
  • 전역 구성은 data-app-data에, 파일별 메타데이터는 data-file-data에, 작은 요소별 값은 개별 data-* 속성에 둡니다. 전체 참조는 클라이언트로의 데이터 흐름을 참고합니다.
  • 내비게이션과 첫 번째로 보이는 diff 사이에 지연을 추가하지 않습니다. 변경이 크리티컬 패스에 비용을 추가한다면 그 비용을 미루거나 없앱니다.

HTML과 스타일#

  • diff 파일 템플릿 안에서 Tailwind 유틸리티 클래스를 사용하지 않습니다. Tailwind 클래스를 쓴 diff 줄 하나는 짧은 rd- 클래스 이름을 쓴 줄보다 3~5배 커질 수 있습니다. 수천 줄에 걸치면 이 차이는 상당합니다.
  • diff 파일 본문 안에 JSON blob을 포함하지 않습니다. 한 번만 구문 분석되는 <diff-file> 요소의 data-file-data를 사용하고, 작은 값에는 특정 요소의 data-* 속성을 사용합니다.
  • 깊게 중첩된 래퍼 요소를 피합니다. 수천 줄에 걸쳐 곱해지는 추가 <div> 하나하나가 구문 분석 시간과 메모리에 측정 가능한 오버헤드를 더합니다.
  • 레거시 스타일과 충돌하지 않도록 모든 CSS 클래스에 rd- 접두사를 붙입니다.
  • 인라인 스타일을 피합니다. 스타일은 SCSS 페이지 번들에 정의합니다.
  • 깊게 중첩된 선택자를 피합니다. 한 단계 클래스 정의를 선호합니다.
  • 고정 헤더와 사이드바 너비와 같은 페이지별 오프셋에는 CSS 변수를 사용합니다. 컴포넌트 스타일이 아니라 페이지 번들에 정의합니다.

어댑터와 런타임#

  • 개별 요소에 리스너를 연결하지 않습니다. 위임된 clicks 핸들러나 어댑터 수명 주기 이벤트를 사용합니다.
  • 필수가 아닌 작업은 크리티컬 렌더링 경로 이후로 미룹니다. 파일이 표시된 후 적용되는 작업에는 VISIBLE/INVISIBLE 핸들러를 사용합니다.
  • 복잡한 컴포넌트는 미리 마운트하지 말고 첫 사용자 상호작용 시점에 마운트합니다.
  • 중간 상태는 클로저가 아니라 this.sink에 저장합니다. 큰 DOM 참조를 캡처하는 클로저는 메모리 누수를 일으킵니다.
  • 모든 이벤트 리스너와 DOM 참조를 onUnmounted에서 정리합니다. Pinia 스토어나 Vue 컴포넌트처럼 어댑터 밖에 DOM 참조를 저장한다면, 해당 참조도 onUnmounted에서 지웁니다. 그렇게 하지 않으면 분리된 DOM 트리가 메모리에 남습니다.
[MOUNTED](onUnmounted) {
  const handler = () => { /* ... */ };
  this.diffElement.addEventListener('input', handler);
  onUnmounted(() => {
    this.diffElement.removeEventListener('input', handler);
  });
},

접근성#

Rapid Diffs는 WCAG 2.1 및 ATAG 2.0 지침의 AA 수준을 준수해야 합니다.

  • 이미지와 같은 텍스트가 아닌 diff 콘텐츠에는 텍스트 대안을 제공합니다.
  • 모든 상호작용 요소를 키보드로 조작할 수 있게 합니다. 파일 토글, 펼치기 컨트롤, 토론 스레드, 옵션 메뉴는 마우스를 요구하지 않아야 합니다.
  • 보조 기술 사용자가 파일, hunk, 토론 사이를 이동할 수 있도록 시맨틱 HTML과 적절한 제목 계층 구조를 사용합니다.
  • 보기 모드, 공백 설정, 파일 브라우저 표시 여부와 같은 사용자 환경설정을 세션 간에 유지합니다.
  • Pajamas 접근성 개발자 체크리스트를 따릅니다.