给 Kubernetes 博客提交文章

Kubernetes 有两个官方博客，CNCF 也有自己的博客频道，你也可以在 CNCF 博客频道上发布与 Kubernetes 相关的内容。对于 Kubernetes 主博客， 我们（Kubernetes 项目组）希望发布与 Kubernetes 有关联的具有不同视角和独特关注点的文章。

除非有特殊情况，我们只发布尚未在其他任何地方投稿或发布的内容。

为 Kubernetes 博客撰写文章

作为一名作者，你有三个渠道来发表文章。

推荐的渠道

Kubernetes 项目推荐的方式是：联系并向博客团队投稿。你可以通过 Kubernetes Slack 频道 #sig-docs-blog 联系他们。 如果你希望文章仅发布在贡献者博客上，也可以直接向 SIG ContribEx 委员会投稿。

除非你的投稿有问题，否则博客团队或 SIG ContribEx 会为你分配：

• 一位博客编辑
• 一位写作搭档（另一位博客作者）

之所以为你分配另一位作者配对，是为了让你们互相支持，互相审阅彼此的文章草稿。 你并不需要非得是某个主题类的专家；大多数读者也不是专家。 Kubernetes 博客团队把为你分配的另一位作者称为“写作搭档”。

编辑会协助你完成从草稿到发表的整个过程。他们可以直接批准文章发布，或安排他人进行批准。

参阅撰写博客文章以了解更多流程信息。

渠道 2：提交 PR

第二种撰写博客的渠道是直接在 GitHub 提交 PR。 不过博客团队并不推荐这种方式；GitHub 很适合协作开发代码，但不太适合处理纯文本写作。

你完全可以先提交一个不包含任何 Commit 的占位 PR，然后在其他地方写好后再把文章推送到此 PR。

与推荐渠道类似，我们会尝试为你配对一位写作搭档和一位博客编辑。 他们会协助你让文章达到发布就绪的状态。

渠道 3：发版后的博文流程

第三种渠道适合 Kubernetes 新版本发版时讲述版本变更的博客文章。 Kubernetes 每次发版时，Release Comms 团队会接手管理博客发布日程。 如果你是为某个版本添加特性的人员或计划发布项目所需其他变更的人员， 可以联络 Release Comms，规划、撰写、编辑并最终发布博客文章。

文章时间安排

对于 Kubernetes 博客，博客团队通常安排在工作日（美国等国家使用的公历）发布文章。 如果很重要，有必要在周末发布文章，博客团队会尽力配合。

在撰写博客文章一节中说明了：

• 起初无需指定文章的发布日期
• 但需要将文章标记为 Draft（在 Front Matter 中添加 draft: true）

当 Prow 机器人处理你提交的 PR 时，起初它是一个 Draft（草稿），不会设置为待发布。 随后 Kubernetes 的一名贡献者（你、你的写作搭档或博客团队的其他人）会提交一个小的跟进 PR，将你的 PR 标记为待发布。 Prow 机器人接受第二个跟进 PR 后会修改之前标记为 Draft 的文章状态，这样你的 PR 就可以自动发布。

到了文章计划发布的那一天后，自动化流程会触发网站构建，让你的文章对大众可见。

撰写文章

在你投稿之后，我们会鼓励你使用 HackMD（一种 Web 版 Markdown 编辑器）或 Google 文档来分享可编辑版本的文章。 你的写作搭档可以阅读你的草稿文字，并直接提出建议或反馈。 如果你写的内容不符合博客指南，他们也会指出来。

同时，你通常也会是他们的写作搭档， 可以参考我们的写作搭档指南支持他们的工作。

初始管理步骤

如果你尚未签署 CLA，应当先签署 CLA。 最好尽早完成 CLA 的签署。如果你是在工作岗位上把撰写文章作为一部分工作， 你可能需要与公司法律团队或上级主管确认你是否允许签署 CLA。

草拟初稿

博客团队建议你使用 HackMD（一个 Web 版的 Markdown 编辑器）或 Google 文档来准备和分享可编辑版本的文章初稿。

你的写作搭档可以对你的草稿文字进行评论和反馈，并检查是否符合博客指南。 与此同时，你也是他们的写作搭档， 参考编辑指南了解如何支持搭档的工作。

你在这个阶段无需顾虑 Markdown 格式是否完美。

如果有图片，你可以粘贴位图副本获取初期反馈。博客团队会（在后续流程中）协助你让插图达到最终发布状态。

Markdown 发布

你可以参考 GitHub 中已有博客文章的 Markdown 格式： 网站仓库。

如果你还不熟悉，参阅贡献基本知识。 本节假设你没有本地克隆的 Fork，假设你是通过 GitHub 网页 UI 操作的。 如果你还未这样操作，你需要先远程 Fork 网站仓库。

在 GitHub 仓库中，点击 Create new file 按钮。 复制 HackMD 或 Google Docs 上写好的内容，粘贴到编辑器中。 下文会说明有关如何进入该文件的更多细节。 此文件的命名应与拟定的博客文章标题相匹配，但不要在文件名中包含日期。 博客审阅人员会与你一起确定最终文件名和文章发布日期。

1. 你在保存文件时，GitHub 会引导你完成 PR 流程。

2. 你的写作搭档会审阅你提交的 PR，并与你协作处理反馈和最终细节。 博客编辑会将你的 PR 作为未排期的草稿批准合并。

Front Matter

你撰写的 Markdown 文件应使用 YAML 格式的 Hugo Front Matter。

以下是一个例子：

---
layout: blog
title: "你的文章标题"
draft: true # 发布前会改为 date: YYYY-MM-DD
slug: 小写文字组成的不含空格的链接放在这里 # 可选
author: >
  作者 1（所属机构）,
  作者 2（所属机构）,
  作者 3（所属机构）  
---

• 起初无需指定文章的发布日期
• 但需要将文章标记为 Draft（在 Front Matter 中添加 draft: true）

正文内容

确保使用二级 Markdown 标题（##，不要用 #）作为正文的最顶级标题。 你在 Front Matter 中设置的 title 会作为该页面的一级标题。

你应遵循风格指南，但以下例外：

• 我们允许作者采用自己的写作风格，只要大多数读者能理解要点就行。
• 对于有多位作者的博客文章，或文章开头已明确说明是代表某组织撰写的，可以使用“我们”。 如本节所见，虽然我们在文档中不推荐使用“我们”这样的表述， 但也可以有一些例外。

• 避免使用 Kubernetes 短代码（如 {{< caution >}}）做提醒。 这是因为提醒主要面向的是文档读者，而博客文章并不是文档。
• 对未来的预测性陈述是允许的，但代表 Kubernetes 的官方公告中应慎用。
• 博客文章中所用的代码示例无需使用 {{< code_sample >}} 短代码，通常直接展示更便于维护。

图表与插图

如使用图表、插图或图示，推荐使用 figure shortcode。 你应该设置 alt 属性以避免访问速度不佳的问题。

对于插图或技术图表，应尽量使用矢量图。 博客团队推荐使用 SVG，而非光栅（位图）格式或 Mermaid（但你可以将 Mermaid 源代码作为注释保留）。 我们倾向于 SVG 而非 Mermaid，是因为当维护者升级 Mermaid 或调整图表渲染时，往往无法联系到原文作者确认变更是否合适。

图表指南主要面向 Kubernetes 文档，而非博客文章。 你可以参考，但：

• 无需为图表编号（如图 1、图 2 等）

因为矢量图要求较高，可能对不熟悉流程的投稿人造成困难； Kubernetes SIG Docs 正在寻找降低门槛的方法。 如果你有降低门槛的好主意，欢迎志愿者帮助解决这个问题。

对于照片等其他图像，博客团队强烈建议使用 alt 属性。 如果不希望辅助工具读出图片内容，也可以使用空的 alt 属性，但这种情况较少见。

Commit 消息

当你标记 PR 为“Ready for review”时，每条 Commit 消息应简明总结工作内容。 第一条 Commit 消息应能大致描述整篇博文内容。

良好的 Commit 消息示例：

• Add blog post on the foo kubernetes feature
• blog: foobar announcement

不好的 Commit 消息示例：

• Placeholder commit for announcement about foo
• Add blog post
• asdf
• initial commit
• draft post

压缩 Commit

当你认为文章已准备好合并时，应压缩（Squash） PR 中的 Commit。如果你不清楚如何操作，可以请博客团队协助。