向 Kubernetes 部落格提交文章

有兩個官方 Kubernetes 部落格，CNCF 也有自己的部落格，你也可以在上面介紹 Kubernetes。對於主 Kubernetes 部落格，我們（Kubernetes 專案）喜歡釋出具有不同視角和特別側重點的文章，這些文章與 Kubernetes 相關。

除少數特殊情況外，我們僅釋出尚未在其他地方提交或釋出的原始內容。

為 Kubernetes 部落格撰寫文章

作為作者，你有三種不同的發表途徑。

推薦路線

Kubernetes 專案推薦的方法是：透過聯絡部落格團隊來推銷你的文章。你可以透過 Kubernetes Slack（#sig-docs-blog）進行操作。對於僅想釋出到貢獻者部落格的文章，你也可以直接聯絡 SIG ContribEx comms。

除非你的提交有問題，否則部落格團隊/SIG ContribEx 將為你匹配

• 一名編輯
• 一名寫作夥伴（另一位部落格作者）

當團隊為你匹配另一位作者時，其目的是讓你們兩人透過審閱對方的草稿文章來相互支援。你不必是主題專家；大多數閱讀文章的人也不是專家。我們 Kubernetes 部落格團隊將另一位作者稱為寫作夥伴。

編輯將幫助你完成從草稿到釋出的整個過程。他們將直接批准你的文章釋出，或者安排批准流程。

閱讀撰寫部落格文章以瞭解更多關於此過程的資訊。

從 pull request 開始

第二種為我們的部落格撰寫文章的途徑是直接在 GitHub 上開始一個 pull request。部落格團隊實際上並不推薦這樣做；GitHub 對於程式碼協作非常有用，但並不適合散文文字。

可以只包含一個空 commit 的佔位符 pull request，然後在其他地方工作，然後再返回到你的佔位符 PR，這是完全沒問題的。

與推薦路線類似，我們將嘗試為你匹配一位寫作夥伴和一位部落格編輯。他們將幫助你準備好文章以供釋出。

釋出後部落格文章流程

第三種途徑是關於 Kubernetes 釋出相關變化的部落格文章。每次釋出時，釋出溝通團隊將接管部落格的釋出計劃。為釋出新增功能的人，或者計劃其他專案需要宣佈的變更的人，可以與釋出溝通團隊協調，以計劃、起草、編輯並最終釋出他們的文章。

文章排期

對於 Kubernetes 部落格，部落格團隊通常將部落格文章安排在工作日（公曆，如美國和其他國家使用）釋出。當需要在週末發生的特定日期釋出時，部落格團隊會盡量安排。

關於撰寫部落格文章的部分解釋了該做什麼

• 首先，不要指定文章的日期
• 但是，請將文章設定為草稿（在 front matter 中放入 draft: true）

當 Prow 機器人合併你寫的 PR 時，它將是草稿狀態，不會被設定為釋出。然後，Kubernetes 貢獻者（你、你的寫作夥伴或部落格團隊的某人）將開啟一個小型後續 PR，將其標記為釋出。合併第二個 PR 將釋出之前處於草稿狀態的文章，使其能夠自動釋出。

在文章計劃釋出的那天，自動化將觸發網站構建，你的文章將可見。

撰寫文章

在您推銷後，我們將鼓勵您使用 HackMD（一個 Web Markdown 編輯器）或 Google 文件來共享文章文字的可編輯版本。您的寫作夥伴可以閱讀您的草稿文字，然後直接提出建議或提供其他反饋。他們還應該讓您知道您正在起草的反饋是否符合部落格指南。

同時，您通常將成為他們的寫作夥伴，並可以遵循我們關於支援他們工作的指南。

初步行政步驟

如果您尚未簽署 CLA，則應儘快簽署。最好儘早開始此操作；如果您是作為工作的一部分寫作，您可能需要與您所在公司的法律團隊或經理確認，以確保您被允許簽署。

初步起草

部落格團隊建議您使用 HackMD（一個 Web Markdown 編輯器）或 Google 文件來準備和共享文章文字的初始、即時可編輯版本。

您的寫作夥伴可以為您的草稿文字提供評論和/或反饋，並將（或應該）檢查其是否符合指南。同時，您將成為他們的寫作夥伴，並可以遵循解釋您如何支援他們工作的指南。

在此階段，請不要過於擔心 Markdown 格式是否完全正確。

如果您有圖片，可以貼上一個位圖副本以供早期反饋。部落格團隊可以在稍後的過程中幫助您準備插圖以供最終釋出。

用於釋出的 Markdown

請檢視 GitHub 中的網站儲存庫中現有部落格文章的 Markdown 格式。

如果您還不熟悉，請閱讀貢獻基礎知識。本頁的這一部分假設您沒有本地克隆的 fork，並且您正在使用 GitHub Web UI 工作。如果您還沒有，您確實需要建立一個遠端 fork（fork）網站儲存庫。

在 GitHub 儲存庫中，點選“建立新檔案”按鈕。從 HackMD 或 Google Docs 複製現有內容，然後貼上到編輯器中。在本節的後面有更多關於該檔案內容的詳細資訊。將檔案命名為與部落格文章的擬議標題相匹配，但不要在檔名中包含日期。部落格審閱者將與您一起確定最終檔名和文章的釋出日期。

1. 儲存檔案後，GitHub 將引導您完成 pull request 流程。

2. 您的寫作夥伴可以審閱您的提交，並與您一起處理反饋和最終細節。部落格編輯會批准您的 pull request 以合併，作為尚未排期的草稿。

Front matter

您編寫的 Markdown 檔案應使用 YAML 格式的 Hugo front matter。

例如：

---
layout: blog
title: "Your Title Here"
draft: true # will be changed to date: YYYY-MM-DD before publication
slug: lowercase-text-for-link-goes-here-no-spaces # optional
author: >
  Author-1 (Affiliation),
  Author-2 (Affiliation),
  Author-3 (Affiliation)  
---

• 首先，不要指定文章的日期
• 但是，請將文章設定為草稿（在文章的front matter中放入 draft: true）

文章內容

請確保使用二級 Markdown 標題（## 而不是 #）作為文章的最高標題級別。您在 front matter 中設定的 title 將成為該頁面的第一級標題。

您應遵循風格指南，但有以下例外：

• 我們允許作者以自己的寫作風格寫文章，只要大多數讀者都能理解其要點即可。
• 可以使用“我們”來撰寫有多位作者的文章，或者當文章引言清楚表明作者代表特定團體寫作時。正如您從本節注意到的，儘管我們在文件中避免使用“我們”，但在可以證明例外的情況下使用它是可以的。
• 我們避免在 Kubernetes 中使用短程式碼（shortcodes）來表示呼籲（例如 {{< caution >}}）。這是因為呼籲是針對文件閱讀者的，而部落格文章不是文件。
• 關於未來的陳述是可以的，儘管我們在代表 Kubernetes 發表官方公告時會謹慎使用。
• 部落格文章中使用的程式碼示例不需要使用 {{< code_sample >}} 短程式碼，而且通常情況下不使用它們更好（更容易維護）。

圖表和插圖

對於插圖、圖表或示意圖，如果可行，可以使用figure 短程式碼。為了無障礙訪問，您應設定 alt 屬性。

對於插圖和技術圖表，請嘗試使用向量圖形。部落格團隊推薦使用 SVG 而非柵格（點陣圖/畫素）圖表格式，同時也推薦 SVG 而非 Mermaid（您仍然可以在註釋中捕獲 Mermaid 原始碼）。偏好 SVG 而非 Mermaid 是因為當維護者升級 Mermaid 或更改圖表渲染時，他們可能無法輕鬆聯絡原始部落格文章作者來檢查更改是否 OK。

《圖表指南》是針對 Kubernetes 文件的，而不是部落格文章。遵循它仍然很好，但是：

• 無需將圖表標註為圖 1、圖 2 等。

對可縮放（向量）影像的要求增加了對不太熟悉的人提交文章的難度；Kubernetes SIG Docs 將繼續尋找降低這一門檻的方法。如果您有關於如何降低門檻的想法，請志願提供幫助。

對於其他圖片（如照片），部落格團隊強烈鼓勵使用 alt 屬性。如果無障礙軟體不應提及圖片，可以使用空的 alt 屬性，但這是一種罕見情況。

Commit 訊息

當您將 pull request 標記為可審閱時，每個 commit 訊息都應該是對正在進行的工作的簡短總結。第一個 commit 訊息應作為部落格文章的整體描述而有意義。

良好 commit 訊息的示例

• 為 foo Kubernetes 功能新增部落格文章
• 部落格：foobar 公告

不良 commit 訊息的示例

• foo 公告的佔位符 commit
• 新增部落格文章
• asdf
• 初始 commit
• 草稿帖子

Squashing

一旦您認為文章已準備好合併，您應該壓縮（squash）您的 pull request 中的 commits；如果您不確定如何操作，可以向部落格團隊尋求幫助。