向 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;如果您不確定如何操作,可以向部落格團隊尋求幫助。