Prometheus logo

Prometheus

文件下載社群支援與培訓部落格

Ctrl + K

GitHub Logo

參與貢獻

貢獻者指南

本文件為各種經驗水平的貢獻者提供了一般指南。

如果您是新貢獻者，您可能希望先檢視如何選擇要處理的工作。

如果您是想要貢獻程式碼的經驗豐富的貢獻者，請檢視高層次流程。

如果您已經有了更深入的具體計劃，請參考提案流程。

本文件是 prometheus/prometheus 倉庫的指南。其中大部分內容也適用於 Prometheus 社群中的其他倉庫，但這些專案可能擁有自己的指南和規則。有關特定倉庫的資訊，請檢視每個倉庫的 README.md 和 CONTRIBUTING.md 檔案。

如何讓 PR 被合併

如果您正在進行首次貢獻，請閱讀整篇文件。本節主要針對經驗豐富的開源貢獻者。

  • 使用 make test 在本地測試更改，並儘可能為您的更改新增測試。
  • 為了避免在 CI 中出現 lint 失敗，執行 make common-format 和 make lint 並修復問題是很有幫助的。
  • 使用 git commit -s 提交以簽署 DCO。
  • 通常，請針對倉庫的預設分支（最常見的是 main，有時是 master）提交 PR。審查人員會協助處理異常情況。
  • 系統會自動指派審查人員。我們的目標是及時做出回應，但其他優先事項可能會導致延遲。
  • 檢查失敗的 CI 任務結果，所有任務都應該成功。
  • 審查人員可能會要求修改。快速處理這些意見將縮短 PR 的週轉時間。

有關我們 GitHub 流程的更多詳細資訊，請參閱 GitHub 指南。

交流渠道

常規的使用者社群渠道旨在討論 Prometheus 的使用，包括在非 Prometheus 開發中使用 Prometheus 程式碼（例如，使用 Prometheus 插樁庫對程式碼進行插樁）。Prometheus 元件本身的開發則透過本節所述的其他渠道進行。

GitHub

貢獻將在 GitHub 的 Pull Request 中進行審查。詳情請參閱下文的 GitHub 指南。GitHub Issue 通常是討論特定 Bug 和功能需求的良好方式。對於非正式或全域性性的討論，下面提到的其他渠道可能會更合適。

CNCF Slack

大量的非正式聊天式討論發生在 CNCF Slack  上。主要的開發頻道是 #prometheus-dev，但還有許多專業頻道。可以尋找形如 #prometheus-...-dev 的頻道名稱，例如 #prometheus-protobuf-dev。

請注意，Slack 是一個資訊孤島。其內容不會被外部搜尋引擎索引，沒有簡單的方法可以匯出和存檔內容，甚至只讀訪問也需要登入。因此，請將 Slack 中的所有內容視為短暫的且公眾無法獲取的。Slack 內容也不會永久儲存。重要資訊（如討論結果）也應透過其他渠道（例如在 GitHub 或郵件列表）釋出，以使其可訪問且持久。避免在其他媒體中連結到 Slack 訊息而不同時總結所連結訊息的內容。

開發者郵件列表

prometheus-developers  郵件列表（映象 ）適用於釋出公告以及對全域性性主題進行更正式的討論。郵件列表存檔會被搜尋引擎索引，因此是尋找過去討論並確保資訊不會丟失在類似 Slack 這樣的資訊孤島中的好方法。

開發者峰會

開發者峰會是討論更深入開發主題的公開會議。有關日程安排、會議記錄和許多其他詳細資訊，請參閱下文的專用章節。

工作組

如果針對特定主題工作的開發者希望或多或少定期舉行線上會議，他們會組建一個工作組。工作組會議是公開的，並透過 Prometheus 日曆  釋出。

如何選擇要處理的工作

最適合著手的功能或 Bug 應該是對您而言重要的東西。可以是您已經是其使用者甚至是專家的領域，也可以是您想要成為專家的領域。

Prometheus 社群透過以下兩種方式幫助識別適合著手解決的 Issue

  1. 尋找帶有 good-first-issue 標籤的 Issue。該標籤標識了我們認為適合任何新貢獻者作為起步的良好任務。
  2. 如果您正在尋找更復雜的 Issue 來解決，請尋找 triage/accepted 標籤。該標籤表明 Issue 已經過分流分類，收集了所有必需的資訊，可以開始著手工作。標籤 triage/needs-triage 和 triage/needs-information 意味著目前還沒有人有時間檢視該 Issue，或者需要更多資訊。請不要處理標記為 triage/needs-triage 或 triage/needs-information 的 Issue。

提案流程

對於較大的更改和想法，我們要求在提案倉庫 中提交正式的提案並進行審查。詳情請閱讀已接受的關於提案流程的提案 。

GitHub 指南

提交資訊應描述提交中做出的修改。我們對於提交的大小沒有強烈的看法，請用您最好的判斷來建立一系列符合邏輯的更改。好的提交能使審查更容易，從而能夠更快地合併。例如，先提交一個新增測試以暴露 Bug 的 Commit，然後再提交一個修復該 Bug 的獨立 Commit，這是一個很好的模式。提交資訊必須包含 Signed-off-by: <作者身份> 行。透過此項，作者同意針對該特定貢獻釋出在 https://developercertificate.org/  上的條款。

一旦您有了想要提議的更改，請將其推送到您個人的 Prometheus 分叉倉庫中，並針對預設分支開一個 Pull Request。預設分支通常是 main，但在某些倉庫中可能是 master。有些情況需要針對釋出分支（例如 release-3.5）開 PR。最常見的情況是修復新版本的候選釋出版，或者是修復 Prometheus 的 LTS 版本。如有疑問，請透過本文件中提到的渠道之一進行諮詢。

系統會自動新增所需的審查人員。任何其他應該或想要審查此更改的人，都可以在評論中提及他們的使用者名稱，但請避免無故提及無關的社群成員。

我們在每個 PR 上都會執行檢查。要進行合併，所有檢查都必須透過。PR 作者應當調查並處理任何失敗的檢查。

審查人員可能會要求修改。在審查期間，PR 透過追加修正提交來不斷演進是常見做法。審查人員在合併時可能會將這些提交壓縮成一組連貫的提交，但應確保最終的提交資訊是有意義的，而不是自動生成的。或者，審查人員可能會要求作者在合併前將提交整理到合理的範圍。為 Pull Request 進行分支變基通常是沒有問題的。只有當其他人已經基於尚未合入 main 分支的提交進行了修改時，提交作者才應避免重寫這些提交。如果一個 PR 變得過大或混雜了無關的關注點（例如重構和邏輯修改），請考慮將其拆分為單獨的 PR，以便於審查。

AI 生成的貢獻

Prometheus 的作者們並不排斥使用 AI 工具來生成程式碼。然而，我們要求在每次提交中都簽署 DCO ，藉此作者證明該貢獻完全或部分由作者創作，且他們有權提交。或者，如果該貢獻基於先前的作品，則該作品應受適當的開源許可證保護，並且作者根據該許可證有權提交帶有修改的該作品。有關更多詳細資訊，請參閱 https://www.linuxfoundation.org/legal/generative-ai 。人類作者必須完全理解他們提交的程式碼。請在提交前考慮 DCO 並仔細審查 AI 生成的程式碼。我們鼓勵明確披露 AI 工具的使用情況，例如透過在相應的提交中新增 Assisted-by: <所使用的 AI 工具名稱>。

對於圍繞 Issue 和 PR 的討論，我們強烈傾向於與人類進行對話。

程式碼風格

關於特定語言的程式碼風格，其他地方已經有很多論述。對於 Prometheus 的貢獻，請遵循以下原則：

  • 使用該語言的地道（idiomatic）程式碼。
  • 保持與周圍已有程式碼一致的風格。不要將風格改進與程式碼邏輯修改混為一談。
  • 我們有大量的 Linter，請使用 make format、make lint 和 make style 來正確格式化您的程式碼。
  • 使用正確的英語語法和標點符號。不要進行無謂的縮寫。
    • 錯誤：// batchQueue full, try again later
    • 正確：// The batchQueue is full, so we need to try again later.
  • 在 Markdown 中，除非行尾是 URL，否則請將行寬限制在 80 個字元以內，而不是一個段落只寫成一行。這會讓在審查中發表評論變得容易得多。

Go 風格指南

Go 是 Prometheus 及其生態系統中使用的主要程式語言。基於 Go 的專案往往遵循非常相似的風格，Prometheus 也不例外。
https://golang.com.tw/wiki/CodeReviewComments  是瞭解具體細節的極佳資源。除此之外，我們還有幾條值得在此提及的規則：

  • 通常我們會將命名的匯入放在一個單獨的塊中。這些塊應按標準庫（stdlib）/ 其他倉庫 / 當前倉庫進行分組。
  • 匯出型別的文件註釋並沒有被 Linter 強制要求（因為存在太多誤報），但我們確實很在乎。請在有意義的地方使用它們。
  • 按照以下方式將過長的函式簽名拆分為多行：在第一行以左括號結束，然後根據需要將函式引數分散在任意數量的行中，最後以獨立的一行並以右括號開頭。例如：
func (s *shards) sendSamples(
	ctx context.Context, samples []prompb.TimeSeries,
	sampleCount, exemplarCount, histogramCount int,
	pBuf *proto.Buffer, buf compression.EncodeBuffer, compr compression.Type,
) error {

不要這樣：

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

或

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

Developer summits usually happen on the last Thursday each month as an online
meeting. See the [Prometheus
calendar](https://calendar.google.com/calendar/u/0/embed?src=prometheus.io_bdf9qgm081nrd0fe32g3olsld0%40group.calendar.google.com)
for the current schedule. In addition, we aim for all-day in-person summits
whenever enough active Prometheus developers are gathered at one place for some
reason, typically at a conference like [PromCon](https://promcon.io/) or
[Kubecon EU](https://events.linuxfoundation.org/kubecon-cloudnativecon-europe/).

The online meetings are open for everyone, while the in-person meetings might
have some restrictions for logistical reasons. If in doubt, ask via the channels
listed above, and we'll see what can be done. We also try to make in-person
summits accessible for online participants on a best-effort basis.

The Prometheus team curates the agenda based on recent discussions via other
channels. You can propose a topic explicitly by adding it at the top of the
meeting notes (see below) or by sending a mail to the [developer mailing
list](https://groups.google.com/forum/#!forum/prometheus-developers) at least
24 hours prior to the summit.

### Meeting notes

We maintain [rolling meeting notes
document](https://docs.google.com/document/d/1uurQCi5iVufhYHGlBZ8mJMK_freDFKPG0iYBQqJ9fvA) (current version starting 2024-09-13).

Historical meeting notes:

- [2017 developer summit notes](https://docs.google.com/document/d/1DaHFao0saZ3MDt9yuuxLaCQg8WGadO8s44i3cxSARcM)
- [2018 developer summit notes](https://docs.google.com/document/d/1-C5PycocOZEVIPrmM1hn8fBelShqtqiAmFptoG4yK70)
- [2019 developer summit notes](https://docs.google.com/document/d/1NQIX78nwBhfLZD3pAb0PK-uBKYqnkzjjVhOQ-kIaEGU)
- [2019 developer summit 2 notes](https://docs.google.com/document/d/1VVxx9DzpJPDgOZpZ5TtSHBRPuG5Fr3Vr6EFh8XuUpgs)
- [2020 virtual developer summit 1 notes](https://docs.google.com/document/d/1yuaPKLDvhJNXMF1ubsOOm5kE2_6dvCxHowBQIDs0KdU)
- [2020 virtual developer summit 2 notes](https://docs.google.com/document/d/1vhXKpCNY0k2cbm0g10uM2msXoMoH8CTwrg_dyqsFUKo)
- [2020 virtual developer summit 3 notes](https://docs.google.com/document/d/18Jbl5LC_FPLqCqU12qY8XpjVMJLCtGt-ykbyAhYXcIc)
- [2020 virtual developer summit 4 notes](https://docs.google.com/document/d/1_60pplXWF1R-utJtswJYFf8F9HBAJdDS5x4Lv9CgAJ8)
- [2020 virtual developer summit 5 notes](https://docs.google.com/document/d/1iO1QHRyABaIpc6xXB1oqu91jYL1QQibEpvQqXfQF-WA)
- [2021 virtual developer summit 1 notes](https://docs.google.com/document/d/10o4gkjgK46MdUHTowpUG_pyeON3Z5k0CbPBqQ211KOE)
- [2021-2024 developer summit rolling notes](https://docs.google.com/document/d/11LC3wJcVk00l8w5P3oLQ-m3Y37iom6INAMEu2ZAGIIE)

### Facilitator

The Facilitator role was created to help the Prometheus team to run the
Developer Summits effectively. It's a rotational role (switches for
every meeting) and its responsibilities are spread across different
phases of the summit:

#### Before the summit

Before the summit, the Facilitator's main goal is to help the
Prometheus team define the agenda and the topics to be discussed while
making sure interested parties of the most voted topics will be able to
attend the summit. We suggest the following tasks:

- Two or three days before the meeting, send reminders in our public
  community channels inviting people to add Agenda Topics, and
  Prometheus Team members and maintainers to vote on topics they'd
  like to discuss.
- One day before the meeting, reach out to "Topic owners" who
  received the most votes to make sure they'll make it to the summit.

#### During the summit

During the summit, the Facilitator is there to make sure that the meeting runs
smoothly, and that consensus is reached when needed. We suggest the
following tasks:

- Start the meeting on time. Use `@prometheus.io` account for the admin meeting
  permissions.
- Start the recording and mention that the Code of Conduct applies.
- Select topics to be discussed based on votes and who is currently present in
  the meeting.
- Take notes or find volunteer for taking notes in the shared document.
- Strategically step in when the discussion is not moving forward or deviating
  from the topic.
- Call for consensus when needed.

#### After the summit

Once the meeting is over, the last task of the Facilitator is to find a new
Facilitator for the next summit by sending an email to the Prometheus Team
mailing list.

本頁內容