Skip to content

Commit 0bbfc1c

Browse files
author
Tim Bannister
committed
Add guide to blog contributions
Add a dedicated section about contributing to the Kubernetes official blogs.
1 parent 70c8f20 commit 0bbfc1c

14 files changed

+717
-274
lines changed

‎content/en/docs/contribute/_index.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,15 @@ card:
1414
<!-- overview -->
1515

1616
There are lots of ways to contribute to Kubernetes. You can work on designs for new features,
17-
you can document the code we already have, you can write for our [blog](/blog). There's more:
18-
you can implement those new features or fix bugs. You can help people join our contributor
19-
community, or support existing contributors.
17+
you can document the code we already have, you can [write for our blogs](/docs/contribute/blog/).
18+
There's more: you can implement those new features or fix bugs. You can help people join our
19+
contributor community, or support existing contributors.
2020

2121
With all these different ways to make a difference to the project, we - Kubernetes - have made
2222
a dedicated website: https://k8s.dev/. You can go there to learn more about
2323
contributing to Kubernetes.
2424

25-
If you specifically want to learn about contributing to _this_ documentation, read
25+
If you specifically want to learn about contributing to _this_ website, read
2626
[Contribute to Kubernetes documentation](/docs/contribute/docs/).
2727

2828
You can also read the

‎content/en/docs/contribute/blog/_index.md

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: Contributing to Kubernetes blogs
3+
slug: blog-contribution
4+
content_type: concept
5+
weight: 15
6+
simple_list: true
7+
---
8+
9+
<!-- overview -->
10+
11+
There are two official Kubernetes blogs, and the CNCF has its own blog where you can cover Kubernetes too.
12+
For the main Kubernetes blog, we (the Kubernetes project) like to publish articles with different perspectives and special focuses, that have a link to Kubernetes.
13+
14+
With only a few special case exceptions, we only publish content that hasn't been submitted or published anywhere else.
15+
16+
Read the [blog content guidance](/docs/contribute/blog/guidelines/#what-we-publish) for more about that aspect.
17+
18+
## Official Kubernetes blogs
19+
20+
### Main blog
21+
22+
The main [Kubernetes blog](/blog/) is used by the project to communicate new features, community reports, and any
23+
news that might be relevant to the Kubernetes community. This includes end users and developers.
24+
Most of the blog's content is about things happening in the core project, but Kubernetes
25+
as a project encourages you to submit about things happening elsewhere in the ecosystem too!
26+
27+
Anyone can write a blog post and submit it for publication.
28+
29+
### Contributor blog
30+
31+
On the [contributor site](https://k8s.dev/), you'll find the Kubernetes
32+
[contributor blog](https://k8s.dev/blog/). This is aimed at an audience of people who
33+
work **on** Kubernetes more than people who work **with** Kubernetes. The Kubernetes project
34+
deliberately publishes some articles to both blogs.
35+
36+
Anyone can write a blog post and submit it for review.
37+
38+
## Article updates and maintenance {#maintenance}
39+
40+
The Kubernetes project does not maintain older articles. For any article published more than 1
41+
year ago, Kubernetes typically does **not** accept issues or pull requests. To avoid establishing precedent,
42+
even technically correct pull requests may be rejected.
43+
44+
However, there are exceptions. These include:
45+
46+
* articles marked as [evergreen](#maintenance-evergreen)
47+
* articles giving advice that is now wrong and dangerous to follow
48+
* fixes to ensure that an existing article still renders correctly
49+
50+
For any article that is over a year old and not marked as _evergreen_, the website automatically
51+
displays a notice that the content may be stale.
52+
53+
### Evergreen articles {#maintenance-evergreen}
54+
55+
You can mark an article as evergreen by setting `evergreen: true` in the front matter.
56+
57+
We only mark blog articles as maintained (`evergreen: true` in front matter) if the Kubernetes project
58+
is happy to commit to maintaining them indefinitely. Some blog articles absolutely merit this; for example, the release comms team always marks official release announcements as evergreen.
59+
60+
## {{% heading "whatsnext" %}}
61+
62+
* Discover the official blogs:
63+
* [Kubernetes blog](/blog/)
64+
* [Kubernetes contributor blog](https://k8s.dev/blog/)
65+
66+
* Read about [reviewing blog pull requests](/docs/contribute/review/reviewing-prs/#blog)

‎content/en/docs/contribute/blog/guidelines.md

+227
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: Blog guidelines
3+
content_type: concept
4+
weight: 40
5+
---
6+
7+
<!-- overview -->
8+
9+
These guidelines cover the main [Kubernetes blog](/blog/) and the Kubernetes
10+
[contributor blog](https://k8s.dev/blog/).
11+
12+
## Original content
13+
14+
The Kubernetes project accepts **original content only**, in English.
15+
16+
{{< note >}}
17+
The Kubernetes project cannot accept content for the blog if it has already been submitted
18+
or published outside of the Kubernetes project.
19+
{{< /note >}}
20+
21+
22+
The official Kubernetes blogs are not the place for vendor pitches or for articles that promote
23+
a specific solution from outside Kubernetes.
24+
25+
This restriction even carries across to promoting other Linux Foundation and CNCF projects.
26+
Many CNCF projects have their own blog. These are often a better choice for posts about a specific
27+
project, even if that other project is designed specifically to work with Kubernetes (or with Linux,
28+
etc).
29+
30+
Articles must contain content that applies broadly to the Kubernetes community. For example, a
31+
submission should focus on upstream Kubernetes as opposed to vendor-specific configurations.
32+
Hyperlinks in articles should primarily be to the official Kubernetes documentation. When using external
33+
references, links should be diverse - For example a submission shouldn't contain only links
34+
back to a single company's blog.
35+
36+
Sometimes this is a delicate balance. You can ask in Slack ([#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J))
37+
for guidance on whether a post is appropriate for the Kubernetes blog and / or contributor blog -
38+
don't hesitate to reach out
39+
40+
The [content guide](/docs/contribute/style/content-guide/) applies unconditionally to blog articles
41+
and the PRs that add them. Bear in mind that some restrictions in the guide state that they are only relevant to documentation; those marked restrictions don't apply to blog articles.
42+
43+
You must write [original content](#original-content) and you must have permission to license that content to the
44+
Cloud Native Computing Foundation (so that the Kubernetes project can legally publish it).
45+
46+
The website is localized into many languages; English is the “upstream” for all the other
47+
localizations. Even if you yourself speak another language and would be happy to provide a localization,
48+
that should be in a separate pull request (see [languages per PR](/docs/contribute/new-content/#languages-per-pr)).
49+
50+
## Blog content guidance {#what-we-publish}
51+
52+
### Content examples
53+
54+
Here are some examples of content that is appropriate for the main Kubernetes blog:
55+
56+
* Announcements about new Kubernetes capabilities
57+
* Explanations of how to achieve an outcome using Kubernetes; for example, tell us about your
58+
low-toil improvement on the basic idea of a rolling deploy
59+
* Comparisons of different software options that have a link to Kubernetes and cloud native. It's
60+
OK to have a link to one of these options so long as you fully disclose your conflict of
61+
interest / relationship.
62+
* Stories about problems or incidents, and how you resolved them
63+
* Articles discussing building a cloud-native platform for specific use cases
64+
your opinion about the good or bad points about Kubernetes
65+
* Announcements and stories about non-core Kubernetes, such as the Gateway API
66+
* [Post-release announcements and updates](#post-release-comms)
67+
* Messages about important Kubernetes security vulnerabilities
68+
* Kubernetes projects updates
69+
* Tutorials and walkthroughs
70+
* Thought leadership around Kubernetes and cloud native
71+
* The components of Kubernetes are purposely modular, so writing about existing integration
72+
points like CNI and CSI are on topic. Provided you don't write a vendor pitch, you can also write
73+
about what is on the other end of these integrations.
74+
75+
76+
Here are some examples of content that is appropriate for the Kubernetes contributor blog:
77+
78+
* Articles about how to test your change to Kubernetes code
79+
* Content around non-code contribution
80+
* Discussions about alpha features where the design is still under discussion
81+
* "Meet the team" articles about working groups, special interest groups etc
82+
* A guide about how to write secure code that will become part of Kubernetes itself
83+
* Articles about maintainer summits and the outcome of those summits
84+
85+
### Examples of content that wouldn't be accepted {#what-we-do-not-publish}
86+
87+
However, the project usually doesn't publish:
88+
89+
* vendor pitches
90+
* an article you've published elsewhere, even if only to your own low-traffic blog
91+
* updates about an external project that works with our relies on Kubernetes (put those on
92+
the external project's own blog)
93+
* articles about using Kubernetes with a specific cloud provider
94+
* articles that criticise specific people, groups of people, or businesses
95+
* articles that have important technical mistakes or misleading details (for example: if you
96+
recommend turning off an important security control in production clusters, because it can
97+
be inconvenient, the Kubernetes project is likely to reject the article).
98+
99+
### Other considerations {#content-considerations-other}
100+
101+
The Kubernetes website has an ICP licence from the government of China. It's unlikely to be a problem but we also cannot publish articles that would be blocked by the Chinese government's official filtering of internet content.
102+
103+
Topics related to participation in or results of Kubernetes SIGs activities are always on
104+
topic (see the work in the [Contributor Comms Team](https://github.com/kubernetes/community/blob/master/communication/contributor-comms/blogging-resources/blog-guidelines.md#contributor-comms-blog-guidelines)
105+
for support on these posts).
106+
107+
The project typically mirrors these articles to both blogs.
108+
109+
110+
- Blog posts should be original content
111+
112+
- The official blog is not for repurposing existing content from a third party as new content.
113+
- The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows
114+
commercial use of the content for commercial purposes, but not the other way around.
115+
116+
- Blog posts should aim to be future proof
117+
118+
- Given the development velocity of the project, we want evergreen content that won't require
119+
updates to stay accurate for the reader.
120+
- It can be a better choice to add a tutorial or update official documentation than to write a
121+
high level overview as a blog post.
122+
- Consider concentrating the long technical content as a call to action of the blog post, and
123+
focus on the problem space or why readers should care.
124+
125+
## Article scheduling
126+
127+
The usual process for submitting a blog article is to
128+
129+
The Kubernetes project typically doesn't guarantee publication on specific dates.
130+
131+
- Articles are reviewed by community volunteers. The blog team tries its to accommodate specific
132+
timing, but they make make no guarantees.
133+
- Even for the release announcements, Kubernetes does not commit to release on the planned
134+
date for a release; the release itself, and the associated announcement article, could
135+
be delayed.
136+
- Many core parts of the Kubernetes projects submit blog posts during release windows, delaying
137+
publication times. Consider submitting during a quieter period of the release cycle.
138+
- If you are looking for greater coordination on post release dates, coordinating with
139+
[CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post.
140+
- Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs,
141+
you can reach out to the blog team on the [`#sig-docs-blog` Slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/)
142+
to ask in real time.
143+
144+
## Technical considerations for submitting a blog post
145+
146+
Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator
147+
for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use
148+
this technology stack.
149+
150+
For illustrations, diagrams or charts, the [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure)
151+
can be used. For other images, we strongly encourage use of alt attributes; if an image doesn't
152+
need any alt attrribute, maybe it's not needed in the article at all.
153+
154+
We recognize that this requirement makes the process more difficult for less-familiar folks to
155+
submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to
156+
lower the barrier, please volunteer to help out.
157+
158+
The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject)
159+
manages the review process for blog posts. For more information, see
160+
[Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post).
161+
162+
To submit a blog post follow these directions:
163+
164+
- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post.
165+
New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts)
166+
directory.
167+
168+
- Ensure that your blog post follows the correct naming conventions and the following
169+
[front matter](https://gohugo.io/content-management/front-matter/) information:
170+
171+
- The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example,
172+
`2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`.
173+
- Do **not** include dots in the filename other than the final `.md` extension.
174+
A name like `2020-01-01-whats-new-in-1.19.md` causes failures during a build.
175+
- The front matter must include the following:
176+
177+
```yaml
178+
---
179+
layout: blog
180+
title: "Your Title Here"
181+
draft: true # will be changed to date: YYYY-MM-DD before publication
182+
slug: lowercase-text-for-link-goes-here-no-spaces # optional
183+
author: >
184+
Author-1 (Affiliation),
185+
Author-2 (Affiliation),
186+
Author-3 (Affiliation)
187+
---
188+
```
189+
190+
- Each commit message should be a short summary of the work being done. The first commit
191+
message should make sense as an overall description of the blog post.
192+
193+
- Examples of a good commit message:
194+
- _Add blog post on the foo kubernetes feature_
195+
- _blog: foobar announcement_
196+
- Examples of bad commit message:
197+
- _Add blog post_
198+
- _._
199+
- _initial commit_
200+
- _draft post_
201+
202+
- The blog team will then review your PR and give you comments on things you might need to fix.
203+
After that the bot will merge your PR and your blog post will be published.
204+
205+
- If the content of the blog post contains only content that is not expected to require updates
206+
to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic
207+
warning about outdated content added to blog posts older than one year.
208+
209+
- To mark a blog post as evergreen, add this to the front matter:
210+
211+
```yaml
212+
evergreen: true
213+
```
214+
- Examples of content that should not be marked evergreen:
215+
- **Tutorials** that only apply to specific releases or versions and not all future versions
216+
- References to pre-GA APIs or features
217+
218+
### Mirroring from the Kubernetes Contributor Blog
219+
220+
To mirror a blog post from the [Kubernetes contributor blog](https://www.kubernetes.dev/blog/), follow these guidelines:
221+
222+
- Keep the blog content the same. If there are changes, they should be made to the original article first, and then to the mirrored article.
223+
- The mirrored blog should have a `canonicalUrl`, that is, essentially the url of the original blog after it has been published.
224+
- Same as [Kubernetes contributor blogs](https://kubernetes.dev/blog), Kubernetes blog posts also mention authors in the YAML header as per the new guidelines. This should be ensured.
225+
- Publication dates stay the same as the original blog.
226+
227+
All of the other guidelines and expectations detailed above apply as well.

‎content/en/docs/contribute/blog/mirroring.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: Blog article mirroring
3+
slug: article-mirroring
4+
content_type: concept
5+
weight: 50
6+
---
7+
8+
<!-- overview -->
9+
10+
There are two official Kubernetes blogs, and the CNCF has its own blog where you can cover Kubernetes too.
11+
For the main Kubernetes blog, we (the Kubernetes project) like to publish articles with different perspectives and special focuses, that have a link to Kubernetes.
12+
13+
If you are not already familiar, you should read up on the differences between the
14+
[main blog](/docs/contribute/blog/#main-blog) and the
15+
[contributor blog](/docs/contribute/blog/#contributor-blog).
16+
17+
Some articles appear on both blogs: there is a primary version of the article, and
18+
a _mirror article_ on the other blog.
19+
20+
<!-- content -->
21+
22+
## Why we mirror
23+
24+
Mirroring is nearly always from the contributor blog to the main blog. The project does this
25+
for articles that are about the contributor community, or a part of it, but are also relevant
26+
to the wider set of readers for Kubernetes' main blog.
27+
28+
As an author (or reviewer), consider the target audience and whether the blog post is appropriate for the main kubernetes.io blog.
29+
For example: if the target audience are Kubernetes contributors only, then kubernetes.dev
30+
may be more appropriate;
31+
if the blog post is about open source in general then it may be more suitable on another site outside the Kubernetes project.
32+
33+
This consideration about target audience applies to original and mirrored articles equally.
34+
35+
The Kubernetes project is willing to mirror any blog article that was published to https://kubernetes.dev/blog/
36+
(the contributor blog), provided that:
37+
38+
- the mirrored article has the same publication date as the original (it should have the same publication time too,
39+
but you can also set a time stamp up to 12 hours later for special cases)
40+
41+
- for PRs that arrive the original article was merged to https://kubernetes.dev/, there haven't been
42+
(and won't be) any articles published to the main blog between time that the original and mirrored article [will] publish.
43+
This is because we (Kubernetes) don't want to add articles to people's feeds, such as RSS, except at the very end of their feed.
44+
45+
- the original article doesn't contravene any strongly recommended review guidelines or community norms.
46+
47+
- the mirrored article will have `canonicalUrl` set correctly in its
48+
[front matter](https://gohugo.io/content-management/front-matter/)
49+
50+
- the audience for the original article would find it relevant
51+
52+
- the article content is not off-topic for the target blog where the mirror article would
53+
appear
54+
55+
## How to mirror
56+
57+
You make a PR against the other Git repsitory (usually,
58+
[https://github.com/kubernetes/website](https://github.com/kubernetes/website)) that adds
59+
the article. You do this _before_ the articles merge.
60+
61+
As the article author, you should set the canonical URL for the mirrored article, to the URL of the original article
62+
(you can use a preview to predict the URL and fill this in ahead of actual publication). Use the `canonicalUrl`
63+
field in [front matter](https://gohugo.io/content-management/front-matter/) for this.

0 commit comments

Comments
 (0)