向 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 文件來準備和共享文章文字的初始、即時可編輯版本。
注意
如果您選擇使用 Google Docs,可以將文件設定為 Markdown 模式。您的寫作夥伴可以為您的草稿文字提供評論和/或反饋,並將(或應該)檢查其是否符合指南。同時,您將成為他們的寫作夥伴,並可以遵循解釋您如何支援他們工作的指南。
在此階段,請不要過於擔心 Markdown 格式是否完全正確。
如果您有圖片,可以貼上一個位圖副本以供早期反饋。部落格團隊可以在稍後的過程中幫助您準備插圖以供最終釋出。
用於釋出的 Markdown
請檢視 GitHub 中的網站儲存庫中現有部落格文章的 Markdown 格式。
如果您還不熟悉,請閱讀貢獻基礎知識。本頁的這一部分假設您沒有本地克隆的 fork,並且您正在使用 GitHub Web UI 工作。如果您還沒有,您確實需要建立一個遠端 fork(fork)網站儲存庫。
在 GitHub 儲存庫中,點選“建立新檔案”按鈕。從 HackMD 或 Google Docs 複製現有內容,然後貼上到編輯器中。在本節的後面有更多關於該檔案內容的詳細資訊。將檔案命名為與部落格文章的擬議標題相匹配,但不要在檔名中包含日期。部落格審閱者將與您一起確定最終檔名和文章的釋出日期。
儲存檔案後,GitHub 將引導您完成 pull request 流程。
您的寫作夥伴可以審閱您的提交,並與您一起處理反饋和最終細節。部落格編輯會批准您的 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;如果您不確定如何操作,可以向部落格團隊尋求幫助。