기여자 가이드

기여자 가이드 (Contributor's guide)

이 문서는 모든 경험 수준의 기여자를 위한 일반 지침이에요. 처음이라면 무엇을 맡을지 고르는 법부터 보면 좋고, 경험 많은 기여자가 변경을 제안하려면 PR을 머지받는 전체 과정을 확인하세요.

이 문서는 prometheus/prometheus 리포지토리를 위한 가이드입니다. 대부분은 Prometheus 커뮤니티의 다른 리포지토리에도 적용되지만, 각 프로젝트마다 자체 가이드와 규칙이 있을 수 있어요. 리포지토리별 정보는 각 리포지토리의 README.md와 CONTRIBUTING.md를 확인하세요.

출처: 문서

본문

이 문서는 모든 경험 수준의 기여자를 위한 일반 지침을 제공합니다.

새로 오셨다면 무엇을 맡을지 고르는 법을 먼저 확인해보세요. 경험 많은 기여자가 변경을 기여하려면 전체 과정을 확인하세요. 더 큰 작업에 대한 구체적인 계획이 이미 있다면 제안 프로세스를 참고하세요.

이 문서는 prometheus/prometheus 리포지토리를 위한 가이드입니다. 대부분은 Prometheus 커뮤니티의 다른 리포지토리에도 적용되지만, 그 프로젝트들은 자체 가이드와 규칙을 가질 수 있습니다. 리포지토리별 정보는 각 리포지토리의 README.md와 CONTRIBUTING.md 파일을 확인하세요.

PR 머지받는 법 (How to get a PR merged)

첫 기여를 하고 있다면 이 문서 전체를 읽어주세요. 이 섹션은 경험 많은 오픈소스 기여자를 위한 것입니다.

  • 가능하면 make test로 변경을 로컬에서 테스트하고, 변경에 대한 테스트를 추가하세요.
  • CI에서 lint 실패를 피하려면 make common-format과 make lint를 실행해 문제를 고치는 게 유용합니다.
  • DCO에 서명하려면 git commit -s로 커밋하세요.
  • 일반적으로 리포지토리의 기본 브랜치(대부분 main, 때로는 master)에 PR을 엽니다. 예외는 리뷰어가 도와줍니다.
  • 리뷰어는 자동으로 배정됩니다. 우리는 제때 응답하려 하지만, 다른 우선순위로 지연될 수 있습니다.
  • 실패한 CI 작업 결과를 확인하세요. 모두 성공할 것으로 기대합니다.
  • 리뷰어가 변경을 요청할 수 있습니다. 이를 빠르게 처리하면 PR의 처리 시간이 단축됩니다.

GitHub 과정에 대한 자세한 내용은 GitHub 지침을 참고하세요.

커뮤니케이션 채널 (Communication channels)

일반적인 사용자 커뮤니티 채널은 Prometheus의 사용법을 논의하기 위한 것입니다. Prometheus 계측 라이브러리로 코드를 계측하는 등 Prometheus 코드를 Prometheus가 아닌 개발에 사용하는 것도 포함됩니다. Prometheus 구성 요소 자체의 개발은 이 섹션에서 설명하는 다른 채널에서 이뤄집니다.

GitHub

기여는 GitHub pull request에서 리뷰됩니다. 자세한 내용은 아래의 GitHub 지침을 참고하세요. GitHub 이슈는 종종 특정 버그와 기능 요청을 논의하는 좋은 방법입니다. 비공식적이거나 전반적인 논의는 아래의 다른 채널이 더 적합할 수 있습니다.

CNCF Slack

비공식적인 대화식 논의의 상당수가 CNCF Slack에서 진행됩니다. 주요 개발 채널은 #prometheus-dev이며, 전문화된 채널도 많습니다. #prometheus-...-dev 같은 채널 이름을 찾아보세요(예: #prometheus-protobuf-dev).

참고로 Slack은 사일로(silo)입니다. 내용이 외부 검색 엔진에 색인되지 않고, 콘텐츠를 내보내거나 아카이브하기 쉬운 방법이 없으며, 읽기 전용 접근에도 로그인이 필요합니다. 따라서 Slack의 모든 것을 일시적이고 일반 대중이 접근할 수 없는 것으로 간주하세요. Slack 콘텐츠는 영원히 보존되지도 않습니다. 논의 결과 같은 중요한 정보는 다른 채널(예: GitHub 또는 개발자 메일링 리스트)에도 게시해 접근 가능하고 영구적으로 만들어야 합니다. 연결된 메시지의 내용을 요약하지 않고 다른 매체에서 Slack 메시지로 연결하는 것을 피하세요.

개발자 메일링 리스트 (Developer mailing list)

prometheus-developers 메일링 리스트(미러)는 공지와 전반적인 주제에 대한 더 공식적인 논의에 적합합니다. 메일링 리스트 아카이브는 검색 엔진에 색인되므로, 과거 논의를 찾고 Slack 같은 사일로에서 정보가 유실되지 않도록 하는 좋은 방법입니다.

개발자 서밋 (Developer summits)

개발자 서밋은 더 심화된 개발 주제를 논의하는 공개 회의입니다. 일정, 회의록 및 기타 세부 사항은 아래의 전용 섹션을 참고하세요.

워크 그룹 (Work groups)

특정 주제를 다루는 개발자들이 정기적으로 온라인 회의를 하려면 워크 그룹을 시작합니다. 워크 그룹 회의는 공개이며 Prometheus 캘린더를 통해 게시됩니다.

무엇을 맡을지 고르는 법 (How to pick something to work on)

작업할 최고의 기능이나 버그는 여러분에게 중요한 것입니다. 이미 사용자이거나 전문가인 것, 또는 전문가가 되고 싶은 것입니다.

Prometheus 커뮤니티는 작업할 좋은 이슈를 찾는 데 두 가지 방식으로 도움을 줍니다:

  • good-first-issue 라벨을 찾으세요. 이 라벨은 새 기여자에게 좋은 출발점이 될 작업을 식별합니다.
  • 더 복잡한 이슈를 찾고 있다면 triage/accepted 라벨을 찾으세요. 이 라벨은 이슈가 분류(triage)되었고, 필요한 모든 정보가 모였으며, 작업을 시작할 수 있음을 나타냅니다. triage/needs-triage와 triage/needs-information 라벨은 아직 아무도 이슈를 살펴볼 시간이 없었거나 더 많은 정보가 필요함을 의미합니다. triage/needs-triage 또는 triage/needs-information 라벨이 붙은 이슈는 작업하지 마세요.

제안 프로세스 (Proposal process)

더 큰 변경과 아이디어에 대해서는 Proposal 리포지토리에서 공식 제안과 리뷰가 필요합니다. 자세한 내용은 수락된 proposal proposal을 읽어주세요.

GitHub 지침 (GitHub guidelines)

커밋 메시지는 커밋에서 만든 변경을 설명해야 합니다. 커밋이 얼마나 크거나 작아야 하는지에 대한 강한 의견은 없으므로, 논리적인 일련의 변경을 만들도록 최선의 판단을 사용하세요. 좋은 커밋은 리뷰를 더 쉽게 만들어 더 빨리 머지될 수 있습니다. 예를 들어 버그를 드러내는 테스트를 추가하는 커밋과, 그 버그를 고치는 별도의 커밋을 두는 것이 좋은 패턴입니다.

커밋 메시지에는 Signed-off-by: 줄이 반드시 포함되어야 합니다. 이를 통해 작성자는 그 특정 기여에 대해 https://developercertificate.org/에 게시된 조건에 동의합니다.

제안할 변경이 생기면 Prometheus의 개인 포크에 푸시하고 기본 브랜치에 pull request를 엽니다. 기본 브랜치는 보통 main이지만 일부 리포지토리에서는 master일 수 있습니다. 어떤 상황에서는 release-3.5 같은 릴리즈 브랜치에 대한 PR이 필요합니다. 가장 흔한 경우는 새 릴리즈의 릴리즈 후보 수정이나 Prometheus의 LTS 버전 수정입니다. 의문이 들면 이 문서에서 언급한 채널 중 하나로 물어보세요.

필요한 리뷰어는 자동으로 추가됩니다. 변경을 리뷰해야 하거나 원하는 다른 사람은 댓글로 사용자 이름을 언급할 수 있지만, 무작위 커뮤니티 멤버를 핑하는 것은 피해주세요.

모든 PR에 실행되는 검사가 있습니다. 머지하려면 모든 검사가 성공해야 합니다. 실패한 검사는 PR 작성자가 조사하고 해결해야 합니다.

리뷰어가 변경을 요청할 수 있습니다. 리뷰 중에 추가 fixup 커밋으로 PR이 진화하는 것은 일반적인 관행입니다. 리뷰어는 머지할 때 이를 일관된 커밋 집합으로 스쿼시할 수 있지만, 최종 커밋 메시지가 의미 있고 자동 생성되지 않도록 해야 합니다. 또는 리뷰어가 작성자에게 머지 전에 커밋을 합리적으로 묶어달라고 요청할 수 있습니다. pull request의 브랜치를 리베이스하는 것은 일반적으로 괜찮습니다. 다른 사람이 main 브랜치에 아직 포함되지 않은 커밋에 기반한 변경을 갖게 되면, 커밋 작성자는 그 커밋을 다시 쓰는 것을 자제해야 합니다. PR이 너무 커지거나 무관한 우려(예: 리팩토링과 로직 변경)를 섞는다면, 리뷰를 쉽게 하기 위해 별도의 PR로 나누는 것을 고려하세요.

AI 생성 기여 (AI generated contributions)

Prometheus 저자는 코드 생성을 위한 AI 도구 사용을 막지 않습니다. 그러나 각 커밋에 DCO를 요구하는데, 이를 통해 작성자는 기여가 작성자에 의해 전체 또는 부분적으로 생성되었으며 제출할 권리가 있음을 증명합니다. 또는 기여가 이전 작업에 기반한 경우 적절한 오픈소스 라이선스로 보호되고 작성자가 수정하여 그 작업을 제출할 권리가 있음을 증명합니다. 자세한 내용은 https://www.linuxfoundation.org/legal/generative-ai를 참고하세요.

인간 작성자는 제출하는 코드를 완전히 이해해야 합니다. DCO를 고려하고 제출 전에 AI 생성 코드를 신중히 리뷰하세요. AI 도구 사용을 명시적으로 공개하는 것을 권장하며, 예를 들어 해당 커밋에 Assisted-by: 를 추가하는 방식입니다.

이슈와 PR에 대한 논의에서는 인간과의 대화를 강력히 선호합니다.

코딩 스타일 (Coding style)

주어진 언어의 코딩 스타일에 대해 다른 곳에서 이미 많이 쓰였습니다. Prometheus 기여는 다음을 지키세요:

  • 언어의 관용적인 코드(idiomatic code)를 사용하세요.

  • 주변의 기존 스타일을 지키세요. 스타일 개선을 코드 변경과 혼동하지 마세요.

  • 린터가 많습니다. 코드를 올바르게 포맷하려면 make format, make lint, make style를 사용하세요.

  • 적절한 영어 문법과 구두점을 사용하세요. 불필요하게 축약하지 마세요.

  • BAD: // batchQueue full, try again later

  • GOOD: // The batchQueue is full, so we need to try again later.

  • Markdown에서는 줄 끝이 URL이 아닌 한, 문단당 한 줄이 아니라 줄 길이를 80자로 제한하세요. 그러면 리뷰에서 주석 달기가 훨씬 쉬워집니다.

Go 스타일 가이드

Go는 Prometheus와 그 생태계에서 사용되는 주요 프로그래밍 언어입니다. Go 기반 프로젝트는 매우 유사한 스타일을 따르는 경향이 있으며, Prometheus도 예외가 아닙니다.

https://go.dev/wiki/CodeReviewComments는 구체적인 내용에 좋은 자료입니다. 그 위에 언급할 만한 몇 가지 규칙이 있습니다:

  • 종종 이름 있는 임포트를 별도 블록에 넣습니다. 블록은 stdlib / 다른 리포지토리 / 같은 리포지토리로 그룹화해야 합니다.
  • 내보낸 타입에 대한 Doc comment는 린터가 강제하지 않지만(거짓 양성이 너무 많아서), 우리는 신경 씁니다. 의미가 있는 곳에서 사용하세요.
  • 긴 함수 시그니처는 다음 방식으로 여러 줄로 나누세요: 첫 줄을 여는 괄호로 끝내고, 함수 파라미터를 원하는 만큼의 줄에 넣은 다음, 닫는 괄호로 시작하는 별도의 줄을 둡니다. 예:
func (s *shards) sendSamples(
	ctx context.Context, samples []prompb.TimeSeries,
	sampleCount, exemplarCount, histogramCount int,
	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type,
) error {

NOT:

func (s *shards) sendSamples(ctx context.Context, samples []prompb.TimeSeries,
	sampleCount, exemplarCount, histogramCount int,
	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type) error {

OR:

func (s *shards) sendSamples(
    ctx context.Context, samples []prompb.TimeSeries,
	sampleCount, exemplarCount, histogramCount int,
	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type) error {

개발자 서밋 세부 사항 (Developer summit details)

개발자 서밋은 보통 매월 마지막 목요일에 온라인 회의로 열립니다. 현재 일정은 Prometheus 캘린더를 참고하세요. 또한 충분히 많은 활성 Prometheus 개발자가 한 장소에 모일 때(PromCon이나 Kubecon EU 같은 컨퍼런스에서 흔히) 종일 대면 서밋을 목표로 합니다.

온라인 회의는 누구에게나 열려 있지만, 대면 회의는 물류적 이유로 일부 제한이 있을 수 있습니다. 의문이 들면 위에 나열된 채널로 물어보세요. 우리는 대면 서밋을 최선을 다해 온라인 참가자에게도 접근 가능하게 만들려고 노력합니다.

Prometheus 팀은 다른 채널을 통한 최근 논의를 기반으로 안건을 선별합니다. 회의록(아래 참조) 상단에 주제를 추가하거나, 서밋 최소 24시간 전에 개발자 메일링 리스트로 메일을 보내 주제를 명시적으로 제안할 수 있습니다.

회의록 (Meeting notes)

우리는 rolling meeting notes 문서(현재 버전 2024-09-13 시작)를 유지합니다.

과거 회의록:

퍼실리테이터 (Facilitator)

퍼실리테이터 역할은 Prometheus 팀이 개발자 서밋을 효과적으로 운영하도록 돕기 위해 만들어졌습니다. 순환 역할(회의마다 교체)이며, 책임은 서밋의 여러 단계에 걸쳐 분산되어 있습니다.

서밋 전 (Before the summit):

서밋 전 퍼실리테이터의 주요 목표는 토론할 안건과 주제를 Prometheus 팀이 정의하도록 돕고, 가장 많은 표를 받은 주제의 이해 관계자가 서밋에 참석할 수 있도록 하는 것입니다. 다음 작업을 제안합니다:

  • 회의 이틀~사흘 전, 공개 커뮤니티 채널에서 사람들이 안건 주제를 추가하도록, 그리고 Prometheus 팀 멤버와 메인테이너가 토론하고 싶은 주제에 투표하도록 초대하는 알림을 보냅니다.
  • 회의 하루 전, 가장 많은 표를 받은 "주제 소유자(Topic owners)"에게 연락해 서밋에 올 수 있는지 확인합니다.

서밋 중 (During the summit):

서밋 중 퍼실리테이터는 회의가 원활히 진행되고 필요할 때 합의에 도달하도록 하는 역할을 합니다. 다음 작업을 제안합니다:

  • 제시간에 회의를 시작하세요. 관리자 회의 권한에는 @prometheus.io 계정을 사용하세요.
  • 녹음을 시작하고 행동 강령이 적용된다는 점을 언급하세요.
  • 투표와 현재 회의에 참석한 사람들을 기준으로 토론할 주제를 선택하세요.
  • 공유 문서에서 메모를 남기거나 메모할 자원봉사자를 찾으세요.
  • 논의가 진행되지 않거나 주제에서 벗어날 때 전략적으로 개입하세요.
  • 필요할 때 합의를 요청하세요.

서밋 후 (After the summit):

회의가 끝나면 퍼실리테이터의 마지막 작업은 Prometheus 팀 메일링 리스트로 이메일을 보내 다음 서밋의 새 퍼실리테이터를 찾는 것입니다.

더 알아보기 (Learn more)