Druid 문서에 기여하기

Druid 문서에 기여하기 (Contribute to Druid docs)

Apache Druid는 커뮤니티 주도 프로젝트예요. 사소한 수정부터 큰 새 기능까지 문서 기여를 환영해요. 문서 기여자는 기존 내용을 개선하거나 새 내용을 만들 수 있어요.

출처: 문서

본문

Apache Druid는 커뮤니티 주도 프로젝트예요. 사소한 수정부터 큰 새 기능까지 문서 기여를 기쁘게 받아들여요.

Druid 문서 기여자는:

• 기존 내용을 개선하거나
• 새 내용을 만들 수 있어요

시작하기

Druid 문서 기여자는 문서에 대한 이슈를 열거나, pull request (PR)로 변경을 기여할 수 있어요.

오픈소스 Druid 문서는 여기에 있어요:

https://druid.apache.org/docs/latest/design/index.html

Druid 문서를 업데이트해야 한다면, 아래 지침에 따라 Druid 저장소에서 해당 문서를 찾아 업데이트하세요.

Druid 저장소 브랜치

Druid 팀은 master 브랜치에서 작업한 다음 26.0.0 같은 릴리스용 브랜치를 만들어요.

Apache Druid에 기여하는 방법은 CONTRIBUTING.md를 참고하세요.

시작하기 전에

Druid 문서에 처음 기여하기 전에 다음 단계를 완료해야 해요:

1. Druid 저장소를 fork하세요. 여러분의 fork가 origin remote가 돼요.
2. fork를 clone하세요:

   git clone [email protected]:GITHUB_USERNAME/druid.git
   

   GITHUB_USERNAME을 여러분의 GitHub 사용자 이름으로 바꾸세요.
3. fork를 clone한 디렉터리에서 apache/druid를 여러분의 upstream remote로 설정하세요:

   git remote add upstream https://github.com/apache/druid.git
   

4. fork가 origin 저장소로, apache/druid가 upstream 저장소로 표시되는지 확인하세요:

   git remote -v
   

5. GitHub용 이메일이 구성되어 있는지 확인하세요:

   git config user.email
   

   이메일을 설정해야 한다면 GitHub instructions을 참고하세요.
6. 사이트를 로컬에서 빌드할 수 있도록 Docusaurus를 설치하세요. website 디렉터리에서 npm install 또는 yarn install을 실행하세요.

기여하기

기여하기 전에 로컬 master 브랜치와 upstream Apache 브랜치가 최신 상태이고 동기화되어 있는지 확인하세요. 이는 병합 충돌을 피하는 데 도움이 돼요. fork의 master 브랜치에서 다음 명령을 실행하세요:

git fetch origin
git fetch upstream

그다음 다음 두 명령 중 하나를 실행하세요:

git rebase upstream/master
# or
git merge upstream/master

이제 최신 상태이므로 변경할 수 있어요.

작업 브랜치를 만드세요:

git checkout -b MY-BRANCH

MY-BRANCH에 기능 브랜치 이름을 지정하세요.

변경할 파일을 찾으세요. 문서의 모든 소스 파일은 Markdown으로 작성되어 docs 디렉터리에 있어요. 페이지의 URL에는 소스 파일이 있는 하위 디렉터리가 포함돼요. 예를 들어 https://druid.apache.org/docs/latest/tutorials/tutorial-msq-extern.html에 있는 SQL 기반 ingestion 튜토리얼은 tutorials 하위 디렉터리에 있어요.

페이지를 추가한다면 적절한 하위 디렉터리에 새 Markdown 파일을 만드세요. 그런 다음 기존 파일에서 front matter와 Apache 라이선스를 복사하세요. title과 id 필드를 업데이트하세요. 새 페이지가 탐색에 표시되도록 website/sidebars.json에 추가하는 것도 잊지 마세요.

사이트를 빌드하고 변경 사항으로 이동해서 로컬에서 변경을 테스트하세요. website 디렉터리에서 npm run start를 실행하세요. 기본적으로 localhost:3000에서 사이트를 시작해요. 포트 3000이 이미 사용 중이면 거기서부터 포트 번호를 올려요.

링크와 스펠 체커를 로컬에서 실행하려면 다음 명령을 사용하세요:

cd website
# You only need to install once
npm install
npm run build
npm run spellcheck
npm run link-lint

이 단계는 GitHub Action 버전의 체크보다 빠르게 실행되고 PR을 만들기 전에 문제를 알려주므로 검토 과정에서 시간을 절약할 수 있어요.

변경 사항을 fork로 push하세요:

git push --set-upstream origin MY-BRANCH

Druid 저장소로 이동하세요. GitHub가 fork에 새 브랜치가 있음을 인식해야 해요. Druid fork와 브랜치에서 Apache Druid 저장소의 master 브랜치로 pull request를 만드세요.

PR 템플릿은 방대해요. 모든 정보가 필요하지 않을 수 있으므로 작성하면서 필요 없는 섹션을 자유롭게 삭제하세요. PR을 만들면 GitHub가 자동으로 이슈에 라벨을 지정해 검토자가 확인할 수 있게 해요.

문서는 커뮤니티 구성원이 피드백을 제공하는 코드와 유사한 검토 과정을 거쳐요. 검토가 완료되고 변경 사항이 병합되면, 사이트가 다시 게시될 때 라이브 사이트에서 볼 수 있어요.

스타일 가이드

일관된 스타일, 형식, 어조는 문서를 더 쉽게 소비하게 해줘요.

대부분의 스타일 고려사항에서 Apache Druid 문서는 Google Developer Documentation Style Guide를 따릅니다.

스타일 가이드는 기여자와 검토자가 문서 품질을 유지할 수 있게 하는 참조점 역할을 해야 해요.

주목할 만한 스타일 예외

경우에 따라 Google Style이 Druid 문서를 읽고 이해하기 더 어렵게 만들 수 있어요. 이 섹션에서는 그 예외를 강조해요.

SQL 키워드 문법

SQL 키워드와 함수에는 모두 대문자를 사용하되 코드 글꼴은 사용하지 마세요.

tip

Correct

The UNNEST clause unnests array values.

Incorrect

The UNNEST clause unnests array values.

선택적 파라미터와 인자

선택적 파라미터와 인자에 대해서는 선택적 파라미터와 선행 명령을 대괄호로 묶으세요.

tip

Correct

HUMAN_READABLE_BINARY_BYTE_FORMAT(value[, precision])

Incorrect

HUMAN_READABLE_BINARY_BYTE_FORMAT(value, [precision])

Markdown 테이블 형식

테이블을 편집하거나 추가할 때 Markdown 소스 내에서 테이블 형식을 "예쁘게" 만들기 위해 추가 문자를 포함하지 마세요.

일부 코드 편집기는 기본적으로 테이블을 형식화할 수 있어요.

자세한 내용은 개발자 style guide를 참고하세요.

tip

Correct

| Column 1 | Column 2 | Column 3 |
| --- | --- | --- |
| value 1 | val 2 | a-very-long-value 3 |

Incorrect

| Column 1 | Column 2 | Column 3            |
| -------- | -------- | ------------------- |
| value 1  | val 2    | a-very-long-value 3 |

스타일 체크리스트

새 내용을 게시하거나 기존 주제를 업데이트하기 전에 다음 체크리스트로 문서를 감사해 기여가 기존 문서와 일치하는지 확인할 수 있어요:

• 서술적인 링크 텍스트를 사용해요. 링크가 파일을 다운로드하면 그 동작을 명시해요.
• 가능하면 현재 시제를 사용해요.
• 가능하면 부정 구문을 피해요. 즉, 하지 말아야 할 일보다 해야 할 일을 말하도록 하세요.
• 명확하고 직접적인 언어를 사용해요.
• 서술적인 제목을 사용해요.
• 제목이나 표제의 첫 단어로 현재분사나 동명사를 피해요. 빠른 방법은 -ing으로 끝나는 단어로 시작하지 않는 거예요. 예를 들어 "Configuring Druid." 대신 "Configure Druid."를 쓰세요.
• 문서 제목과 표제에는 sentence case를 사용해요.
• 텍스트나 코드 샘플의 이미지를 사용하지 마세요.
• 가능하면 PNG보다 SVG를 사용하세요.
• 각 이미지에 alt text나 동등한 텍스트 설명을 제공해요.
• 적절한 텍스트 형식을 사용해요. 예를 들어 코드 스니펫과 속성 이름은 코드 글꼴로, UI 요소는 굵게 하세요. 특별한 이유가 없으면 특정 단어를 강조하기 위해 bold나 italic을 사용하는 것은 일반적으로 피해야 해요.
• 지시문 앞에 조건절을 두세요. 다음 예시에서 "to drop a segment"가 조건절이에요: to drop a segment, do the following.
• 성별 특정 대명사를 피하고 "they"를 사용해요.
• 2인칭 단수를 사용해요 — "we" 대신 "you".
• American spelling과 Commonwealth/"British" spelling이 다를 때 American spelling을 사용해요.
• 무례한 것으로 간주되는 용어를 사용하지 마세요. Google의 Word list 같은 목록을 지침과 대안으로 참고하세요.
• 곡선형 대신 직선형 따옴표와 아포스트로피를 사용해요.
• 목록, 테이블, 절차를 도입할 때 독자가 무엇을 읽게 될지 준비시키는 도입 문장을 사용해요.

더 알아보기 (Learn more)

• CONTRIBUTING.md — Apache Druid에 기여하는 방법을 알아봐요.
• Druid 공식 문서 — 기여할 대상 문서를 확인해요.