부록: 문서 기여하기
부록: 문서 기여하기 (Appendix: Contributing to Documentation)
Apache HBase 문서에 기여하는 방법과 웹사이트·문서의 구조를 설명하는 페이지예요. 문서 편집부터 패치 제출, 배포 흐름까지 정리되어 있어요.
출처: 문서
본문
문서 기여하기 (Contributing to Documentation)
Apache HBase 프로젝트는 문서를 포함한 프로젝트의 모든 측면에 대한 기여를 환영해요.
HBase에서 문서는 다음 영역을 포함하고, 아마 몇 가지 더도 있을 거예요:
- HBase Reference Guide(이 책)
- HBase 웹사이트
- API 문서
- 커맨드라인 유틸리티 출력과 도움말 텍스트
- Web UI 문자열, 명시적 도움말 텍스트, 컨텍스트 인식 문자열 등
- 로그 메시지
- 소스 파일, 설정 파일 등의 주석
- 위 항목 중 하나를 영어 외의 목표 언어로 현지화하는 것
어떤 영역에 기여하고 싶든, 첫 단계는 거의 항상 HBase 소스 코드를 다운로드(보통 Git 저장소를 clone해서)하고 익히는 거예요. 소스 다운로드·빌드에 대한 정보는 developer를 참고하세요.
다른 문자열에 기여하기 (Contributing to Other Strings)
UI, 유틸리티, 스크립트, 로그 메시지 등 어디서든 문자열에 오류를 발견하거나, 더 명확하게 만들 수 있다고 생각하거나, 현재 존재하지 않는 곳에 텍스트가 추가되어야 한다고 생각한다면, 첫 단계는 JIRA를 등록하는 것이에요. 관련된 다른 구성 요소 외에 반드시 컴포넌트를 Documentation으로 설정하세요. 대부분의 컴포넌트에는 새 이슈를 모니터링하는 하나 이상의 기본 소유자(default owner)가 있어요. 버그를 고칠 수 있다고 생각하는지와 무관하게, 본 버그는 여전히 등록해야 해요.
방금 등록한 버그를 직접 고쳐 보고 싶다면 자신에게 할당하세요. HBase Git 저장소를 로컬 시스템에 clone하고 그 이슈를 작업해야 해요. 잠재적 수정을 개발했으면 검토용으로 제출하세요. 이슈를 해결하고 개선으로 여겨지면 HBase 커미터 중 하나가 상황에 맞게 하나 이상의 브랜치에 커밋할 거예요.
절차: 패치 제출을 위한 권장 작업 흐름 (Procedure: Suggested Work flow for Submitting Patches)
이 절차는 Git 전문가에게 필요한 것보다 더 자세하지만, Git에 익숙하지 않은 사람들이 배우는 동안 HBase에 자신 있게 기여할 수 있도록 이 부록에 포함했어요.
아직 하지 않았다면 Git 저장소를 로컬로 clone하세요. 이 작업은 한 번만 하면 돼요. 추적 브랜치를 체크아웃한 상태에서 git pull 명령으로 자주 원격 변경 사항을 로컬 저장소로 가져오세요. 작업하는 각 이슈마다 새 브랜치를 만드세요. 브랜치 이름을 붙이는 데 잘 작동하는 관례 중 하나는 주어진 브랜치를 관련 JIRA와 같은 이름으로 짓는 것이에요.
$ git checkout -b HBASE-123456
브랜치에서 제안된 변경을 하고, 자주 로컬 저장소에 커밋하세요. 다른 이슈 작업으로 전환해야 한다면 적절한 브랜치를 체크아웃하는 것을 기억하세요. 패치를 제출할 준비가 되면 먼저 수정된 브랜치에서 HBase가 깨끗하게 빌드되고 예상대로 동작하는지 확인하세요. 문서나 웹사이트 변경을 했다면 hbase-website/ 디렉터리에서 개발 서버를 실행해 사이트가 올바르게 빌드되는지 확인하세요. 수정을 구현하는 데 며칠이나 몇 주가 걸리거나, 작업 중인 코드 영역에 최근 변경이 많다는 것을 안다면, 패치 제출 전에 브랜치를 원격 master에 대해 rebase하고 충돌을 처리했는지 확인하세요.
$ git checkout HBASE-123456 $ git rebase origin/master
원격 master에 대해 패치를 생성하세요. git 저장소의 최상위 레벨(보통 hbase라고 함)에서 다음 명령을 실행하세요.
$ git format-patch --stdout origin/master > HBASE-123456.patch
패치 이름에는 JIRA ID가 포함되어야 해요. 실수로 추가 파일을 변경하지 않았고 다른 놀라움이 없는지 패치 파일을 살펴보세요. 만족스러우면 패치를 JIRA에 첨부하고 Patch Available 버튼을 클릭하세요. 검토자가 패치를 검토할 거예요. 패치의 새 버전을 제출해야 한다면 옛것을 JIRA에 남겨두고 새 패치 이름에 버전 번호를 추가하세요. 변경이 커밋된 후에는 로컬 브랜치를 유지할 필요가 없어요.
HBase 웹사이트와 문서 편집 (Editing the HBase Website and Documentation)
HBase 웹사이트와 문서는 이제 Remix와 Fumadocs로 빌드된 단일 애플리케이션의 일부예요. 소스 파일은 hbase-website/ 디렉터리에 있어요.
- 문서 페이지:
hbase-website/app/pages/_docs/docs/_mdx/(multi-page)/— 각 문서 섹션의 개별 MDX 파일 - 단일 페이지 보기:
hbase-website/app/pages/_docs/docs/_mdx/single-page/index.mdx— 모든 문서를 한 페이지로 결합 - 웹사이트 컴포넌트:
hbase-website/app/components/— 사이트 전반에 사용되는 React 컴포넌트 - 이미지:
hbase-website/public/— 이미지를 포함한 정적 자산
아무 텍스트 편집기나 IDE에서 MDX 파일을 편집할 수 있어요. 변경을 로컬에서 미리 보려면 hbase-website/ 디렉터리에서 개발 서버를 실행하고 브라우저에서 문서 페이지로 이동하세요. 변경에 만족하면 submit doc patch procedure의 절차를 따라 패치를 제출하세요.
HBase 웹사이트와 문서 게시 (Publishing the HBase Website and Documentation)
HBase 웹사이트와 문서는 단일 Remix 애플리케이션으로 빌드·배포돼요. 배포 프로세스는 프로젝트의 CI/CD 파이프라인으로 관리되며, hbase-website/ 디렉터리에서 사이트를 빌드하고 변경이 main 브랜치에 merge되면 자동으로 배포해요.
MDX 및 Fumadocs 컴포넌트 (MDX and Fumadocs Components)
HBase 문서는 MDX(Markdown with JSX)로 작성되며, 표준 Markdown 구문과 함께 React 컴포넌트를 사용할 수 있어요. Markdown 서식과 MDX 기능에 대한 포괄적 문서는 다음을 참고하세요.
- Fumadocs Markdown Documentation — MDX 구문과 Fumadocs 기능의 완전한 가이드
- CommonMark specification — 표준 Markdown 구문 참고
- GFM (GitHub Flavored Markdown) — GitHub 스타일 Markdown 확장
Fumadocs 컴포넌트
Fumadocs는 문서를 향상시키는 여러 컴포넌트를 제공해요.
Steps 컴포넌트
<Steps>를 사용해 번호가 매겨진 단계별 지침을 만들 수 있어요.
출력 예시:
First, do this thing.Then, do this other thing.
Callout 컴포넌트
메모, 경고, 중요한 정보에는 <Callout>을 사용하세요.
출력 예시:
This is an informational callout.
This is a warning callout.
Include 지시문 (Include Directive)
단일 페이지 문서 보기는 <include> 태그로 여러 MDX 파일을 결합해요.
모든 문서 섹션이 단일 페이지 보기에 어떻게 포함되는지 예시는 hbase-website/app/pages/_docs/docs/_mdx/single-page/index.mdx를 참고하세요.
자동 생성 콘텐츠 (Auto-Generated Content)
default configuration 같은 HBase 문서의 일부는 코드와 동기화되도록 자동 생성돼요. 설정 문서는 hbase-common/src/main/resources/hbase-default.xml 파일에서 생성돼요.
설정 매개변수를 추가·수정하려면 소스 XML 파일을 업데이트하세요. 업데이트된 설정에서 문서를 재생성하려면 다음을 실행하세요.
npm run extract-hbase-config
이 명령은 npm ci를 실행할 때도 자동으로 실행돼요.
문서의 이미지 (Images in the Documentation)
표준 Markdown 구문으로 HBase 문서에 이미지를 포함할 수 있어요. 접근성을 위해 항상 설명적인 alt 텍스트를 포함하세요.
이미지를 hbase-website/public/ 디렉터리나 적절한 서브 디렉터리에 저장하세요. public 디렉터리의 절대 경로로 MDX 파일에서 참조하세요.
이미지를 포함한 패치를 제출할 때는 이미지를 JIRA 이슈에 첨부하세요.
문서에 새 섹션 추가 (Adding a New Section to the Documentation)
HBase 문서에 새 섹션을 추가하려면:
hbase-website/app/pages/_docs/docs/_mdx/(multi-page)/에 설명적인 이름(예:my-new-section.mdx)으로 새 MDX 파일을 만드세요.- 파일 상단에 title과 description이 있는 frontmatter를 추가하세요.
title: "My New Section" description: "Brief description of what this section covers"
My New Section
Your content here...
hbase-website/app/pages/_docs/docs/_mdx/(multi-page)/meta.json의pages배열 내 적절한 위치에 새 파일을 추가하세요(.mdx확장자 없이):
{ "pages": [ "---My Category---", "my-new-section", ... ] }
hbase-website/app/pages/_docs/docs/_mdx/single-page/index.mdx의 적절한 위치에<include>지시문을 추가하세요.
- 패치를 만들기 전에 새 파일을 Git에 추가하세요.
고유 헤딩 요구 사항 (Unique Headings Requirement)
모든 문서 파일이 단일 페이지 보기로 병합되므로, 모든 헤딩 ID는 전체 문서에서 고유해야 해요. 빌드 중 중복 헤딩 ID가 감지되면 테스트가 실패해 문제가 있는 헤딩을 표시해요.
헤딩이 시각적으로 고유할 필요는 없지만 링크 ID는 고유해야 해요. Fumadocs 구문으로 헤딩 ID를 커스터마이즈할 수 있어요.
Configuration [#server-configuration]
이것은 "Configuration"으로 표시되지만 링크용으로 #server-configuration이라는 고유 ID를 가진 헤딩을 만들어요.
목차에서 헤딩 숨기기 (Hiding Headings from Table of Contents)
오른쪽 목차에서 특정 헤딩을 숨길 수 있어요.
Internal Implementation Details [!toc]
이 헤딩은 문서에는 여전히 나타나지만 목차 내비게이션에는 표시되지 않아요.
메모: [!toc]는 헤딩 ID의 일부가 돼요. 예를 들어 ## Usage [!toc]는 #usage-toc라는 ID를 가져요.
커스텀 ID와 TOC 숨기기 결합 (Combining Custom IDs and TOC Hiding)
두 속성을 모두 결합할 수 있어요.
Configuration Details [#server-config] [!toc]
일반적인 문서 이슈 (Common Documentation Issues)
다음 문서 이슈들은 자주 발생해요.
-
쉬운 diff 검토를 위한 변경 격리 (Isolate Changes for Easy Diff Review) 콘텐츠 변경을 할 때 전체 파일을 재포맷하는 것을 피하세요. 파일을 재포맷해야 한다면 콘텐츠를 변경하지 않는 별도의 JIRA에서 하세요.
-
구문 강조 (Syntax Highlighting) MDX는 코드 블록의 구문 강조를 지원해요. 여는 삼중 백틱 뒤에 언어를 지정하세요.
public class Example {
// your code here
}
- 컴포넌트 구문 (Component Syntax)
Fumadocs 컴포넌트를 올바르게 닫는 것을 기억하세요.
<Steps>와<Callout>같은 컴포넌트는 올바르게 닫혀야 해요.
- 고유 헤딩 ID (Unique Heading IDs)
모든 헤딩 ID가 전체 문서에서 고유한지 확인하세요. 중복 헤딩에 대한 테스트 실패가 나오면 Unique Headings Requirement 섹션에 설명된 대로
[#custom-id]구문으로 헤딩 ID를 커스터마이즈하세요.