-
Notifications
You must be signed in to change notification settings - Fork 14.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add guide to blog contributions #50092
base: main
Are you sure you want to change the base?
Conversation
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pull Request Overview
This PR adds a dedicated guide for contributing to Kubernetes blogs. It introduces new pages for blog guidelines, mirroring, post‐release communications, and article submissions, while also updating related indices and review guidelines to better support blog contributions.
Reviewed Changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.
Show a summary per file
File | Description |
---|---|
content/en/docs/contribute/blog/guidelines.md | New blog guidelines document covering original content, blog scheduling, and technical details. |
content/en/docs/contribute/blog/_index.md | New index page for blog contributions with an overview of official blogs. |
content/en/docs/contribute/blog/mirroring.md | New instructions on mirroring blog articles. |
content/en/docs/contribute/blog/release-comms.md | New guide for post-release communications and related procedures. |
content/en/docs/contribute/blog/submission.md | New comprehensive instructions for submitting blog articles. |
content/en/docs/contribute/new-content/case-studies.md | New page for case studies submissions with a minor typo in the link title. |
content/en/docs/contribute/review/reviewing-prs.md | Updated review guidelines for blog-related contributions. |
content/en/docs/contribute/new-content/_index.md | Updated index content with additional links to blog articles and case studies. |
content/en/docs/contribute/new-content/new-features.md | Added a reference to the post-release communications guide in the context of new features. |
content/en/docs/contribute/review/for-approvers.md | Minor wording improvements regarding closing stale blog-related issues. |
content/en/docs/contribute/suggesting-improvements.md | Adjusted weight value to better reflect this page’s importance. |
content/en/docs/contribute/_index.md | Modified text to reference "blogs" instead of a singular "blog" for clarity. |
content/en/docs/contribute/new-content/blogs-case-studies.md | Removed obsolete content that is now covered by updated guidelines. |
✅ Pull request preview available for checkingBuilt without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
0bbfc1c
to
c07ae08
Compare
c07ae08
to
d80c737
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I haven't gone through all the notes yet, but just leaving a few things I noticed! 🙏
We only mark blog articles as maintained (`evergreen: true` in front matter) if the Kubernetes project | ||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We only mark blog articles as maintained (`evergreen: true` in front matter) if the Kubernetes project | |
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. | |
We only mark blog articles as maintained (`evergreen: true` in front matter) if the Kubernetes project | |
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. |
I'm not sure when you'd mark blogs as evergreen
other than Comms use cases. I suppose it's rather rare, and possibly we could highlight that this is usually not the case for most blogs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would prefer not to highlight this @rytswd as we have had instances in the past where evergreen blogs (the Katacoda removal comes to mind, and the dockershim deprecation) are indeed needed, alongside the frequency of release announcements. I see this kind of inclusion as a good case of us being thorough about any possible review, including for release blogs
Articles must contain content that applies broadly to the Kubernetes community. For example, a | ||
submission should focus on upstream Kubernetes as opposed to vendor-specific configurations. | ||
Hyperlinks in articles should primarily be to the official Kubernetes documentation. When using external | ||
references, links should be diverse - For example a submission shouldn't contain only links |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
references, links should be diverse - For example a submission shouldn't contain only links | |
references, links should be diverse. For example, a submission shouldn't contain only links |
Sometimes this is a delicate balance. You can ask in Slack ([#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J)) | ||
for guidance on whether a post is appropriate for the Kubernetes blog and / or contributor blog - | ||
don't hesitate to reach out |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sometimes this is a delicate balance. You can ask in Slack ([#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J)) | |
for guidance on whether a post is appropriate for the Kubernetes blog and / or contributor blog - | |
don't hesitate to reach out | |
Sometimes this is a delicate balance. You can ask in Slack ([#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J)) | |
for guidance on whether a post is appropriate for the Kubernetes blog and / or contributor blog. | |
If in doubt, do not hesitate to reach out! |
for guidance on whether a post is appropriate for the Kubernetes blog and / or contributor blog - | ||
don't hesitate to reach out | ||
|
||
The [content guide](/docs/contribute/style/content-guide/) applies unconditionally to blog articles |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Because there are "Blog content guidance" and "Documentation content guide", it may be better to clarify which one this is about? Also, it may be good to keep the wording consistent, and stick to either "guide" or "guidance"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I made some changes. However, I actually think we'd be better off renaming https://kubernetes.io/docs/contribute/style/content-guide/ and calling it a content policy.
|
||
## Article scheduling | ||
|
||
The usual process for submitting a blog article is to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just noting an unfinished sentence here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for putting this together Tim from our continued blog team conversations – I've done an initial review of the content, but altogether this looks great for our current state.
|
||
### Examples of content that wouldn't be accepted {#what-we-do-not-publish} | ||
|
||
However, the project usually doesn't publish: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
However, the project usually doesn't publish: | |
However, the project will not publish: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sftim the below bullet points don't begin capitalized, whereas the above bullets do – can your next push please address this inconsistency? thanks!
I think merging this makes the site overall better (as it stands today), but I intend to polish and squash this PR when I get time. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sftim that looks great!
It makes the whole process much more clear to the first comers!
I just left some comments/suggestion to fix typos or enhance clarity.
Most of the blog's content is about things happening in the core project, but Kubernetes | ||
as a project encourages you to submit about things happening elsewhere in the ecosystem too! | ||
|
||
Anyone can write a blog post and submit it for publication. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Anyone can write a blog post and submit it for publication. | |
Anyone can [write a blog post and submit it](/docs/contribute/blog/submission) for publication. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't want to link to this here, but I appreciate the suggestion.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(it forces people to read on, and that's actually the outcome we want)
|
||
## Article updates and maintenance {#maintenance} | ||
|
||
The Kubernetes project does not maintain older articles. This means that any published article more than one |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is that valid on both contributor site and main blog?
If yes probably is worth specifying.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I replied to a similar comment: I'd rather not.
* [Kubernetes blog](/blog/) | ||
* [Kubernetes contributor blog](https://k8s.dev/blog/) | ||
|
||
* Read about [reviewing blog pull requests](/docs/contribute/review/reviewing-prs/#blog) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This guide is valid for both contributor site and main blog?
Maybe is woth specifying.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't really want to put "this is valid for all the blogs" everywhere; I kind of hope it can be implicit.
Cloud Native Computing Foundation (so that the Kubernetes project can legally publish it). | ||
|
||
The website is localized into many languages; English is the “upstream” for all the other | ||
localizations. Even if you yourself speak another language and would be happy to provide a localization, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
localizations. Even if you yourself speak another language and would be happy to provide a localization, | |
localizations. Even if you speak another language and would be happy to provide a localization, |
for articles that are about the contributor community, or a part of it, but are also relevant | ||
to the wider set of readers for Kubernetes' main blog. | ||
|
||
As an author (or reviewer), consider the target audience and whether the blog post is appropriate for the main kubernetes.io blog. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As an author (or reviewer), consider the target audience and whether the blog post is appropriate for the main kubernetes.io blog. | |
As an author (or reviewer), consider the target audience and whether the blog post is appropriate for the main Kubernetes blog. |
to the wider set of readers for Kubernetes' main blog. | ||
|
||
As an author (or reviewer), consider the target audience and whether the blog post is appropriate for the main kubernetes.io blog. | ||
For example: if the target audience are Kubernetes contributors only, then kubernetes.dev |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For example: if the target audience are Kubernetes contributors only, then kubernetes.dev | |
For example: if the target audience are Kubernetes contributors only, then the contributor site |
## Authoring an article {#authoring} | ||
|
||
After you've pitched, we'll encourage you to use either HackMD (a web Markdown editor) or a | ||
Google doc, to share an editable version of the article text. Your writing buddy can critique |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Google doc, to share an editable version of the article text. Your writing buddy can critique | |
Google doc, to share an editable version of the article text. Your writing buddy can review |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I want to avoid the word "review" as people might confuse this with pull request review.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Then we could use something like "leave comments/feedback."
"Critique" might sound too harsh.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will do, good idea.
If you choose to use Google Docs, you can set your document into Markdown mode. | ||
{{< /note >}} | ||
|
||
Your writing buddy can critique your text and let you know if it's not in line with the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Your writing buddy can critique your text and let you know if it's not in line with the | |
Your writing buddy can review your text and let you know if it's not in line with the |
cc69f1d
to
ad0820a
Compare
@sftim I agree with your prior comment and am happy to provide another review once you squash and polish so that we can have these changes merged. Thanks again for putting this together! |
ad0820a
to
53eff63
Compare
53eff63
to
443198e
Compare
I'd intended to write about being a writing buddy. Added, hyperlinked, committed, pushed. |
@sftim it might be a good idea to update the SiG-Docs Blog subproject README (https://github.com/kubernetes/community/blob/master/sig-docs/blog-subproject/README.md) adding the distinction between main and maintainer blog, reviewing the existing sections (submit, review and mainenance) to add new details and link to the new pages that will be published after this PR is closed. What do you think? |
@graz-dev I would prefer to hold off on updating the README particularly regarding the maintainer/main blog distinctions, as we're currently in the processes of discussing with ContribEx the idea of merging the two blogs together, and this guide is hoping to serve the purpose of recruiting more reviewers to a combined blog team (alongside the improvements to contributing blogs itself) |
@natalisucks ack! |
/hold This tries not to make too much change, but at the same time it's size/xxl now and is documenting a policy that's clearly different from what is written down today. OK to unhold when there is consensus (or lazy consensus) that we should do that. |
There's a lot of support for one team; what we do about the two separate index pages isn't yet settled. |
f125b55
to
f8ec0ae
Compare
with my SIG Docs co-chair hat on, I support these changes. would love to hear from @divya-mohan0209 @reylejano @katcosgrove @salaxander and @tengqm so we can get leadership consensus. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have glanced over most of this PR & will provide a full-fledged review over the weekend. However, overall, this is the direction I'd like to see us head in.
LGTM!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some comments, mostly focused on the k8s.dev -> website cases.
<!-- overview --> | ||
|
||
There are two official Kubernetes blogs, and the CNCF has its own blog where you can cover Kubernetes too. | ||
Read [contributing to Kubernetes blogs](/docs/contribute/blog/) to learn about these two blogs. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have a different take on this (although similar in spirit) on Contributor Comms, as part of the shadowing programme. Would this be on top of that, or something we should harmonise?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand how I'd change this paragraph to reflect that SIG ContribEx Comms has a shadowing programme. What did you have in mind?
to [SIG ContribEx comms](https://kubernetes.slack.com/archives/C03KT3SUJ20). | ||
<!-- FIXME: or using this [form] --> | ||
|
||
Unless there's a problem with your submission, the blog team / SIG ContribEx will pair you up with: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We have a a similar walk-through of the process here, when this is merged I will open a PR to update it, referencing this one and focusing on the things that are specific to spotlights.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Eventually, I'd like to have one unified process that both teams jointly own and jointly follow.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed, that was the gist of what I said as well, remove things that will be a part of that unified process and only keep the ones that are specific about the Spotlight content. I'll open an issue on this to track it myself.
It is OK to use an empty `alt` attribute if accessibility software should not mention the | ||
image at all, but this is a rare situation. | ||
|
||
#### Commit messages |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we add something about squashing as a best-practice? I can add a simple paragraph on it, including a link to to how to do it using git and prow, but wanted to have your take on it first.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added (see line 228, at time of writing).
@@ -165,56 +167,33 @@ When reviewing, use the following as a starting point. | |||
|
|||
### Blog | |||
|
|||
- Early feedback on blog posts is welcome via a Google Doc or HackMD. Please request input early from the [#sig-docs-blog Slack channel](https://kubernetes.slack.com/archives/CJDHVD54J). | |||
- Before reviewing blog PRs, be familiar with [Submitting blog posts and case studies](/docs/contribute/new-content/blogs-case-studies/). | |||
- We are willing to mirror any blog article that was published to https://kubernetes.dev/blog/ (the contributor blog) provided that: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should add the approach that we've been informally using, namely that reviews should be done in the "original" repository to avoid duplicate (and potentially conflicting) reviews. Does this make sense?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes with a caveat - ideally those happen at HackMD / Google Docs stage.
Would you be willing to write a suggestion on the change to make?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am, will submit one shortly.
f8ec0ae
to
cf87d35
Compare
b1f1ab2
to
d8ea467
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall a good improvement to the guidelines. Some comments around clarity, duplication, and readability (and some nits). I didn't review all of the files (in the new section, I haven't looked at release-comms and submission)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Out of scope: For some reason, the title doesn't show up on this page like it does on other pages. It's like this in the live version as well
content/en/docs/contribute/_index.md
Outdated
|
||
With all these different ways to make a difference to the project, we - Kubernetes - have made | ||
a dedicated website: https://k8s.dev/. You can go there to learn more about | ||
contributing to Kubernetes. | ||
|
||
If you specifically want to learn about contributing to _this_ documentation, read | ||
If you specifically want to learn about contributing to _this_ website, read |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"website" encompasses the kubernetes blog as well, right? maybe, since we're linking to the docs contribution section, say "If you want to learn how to contribute to the Kubernetes documentation on this site, see blah"?
There are two official Kubernetes blogs, and the CNCF has [its own blog](https://www.cncf.io/blog/) where you can cover Kubernetes too. | ||
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. | ||
|
||
With only a few special case exceptions, we only publish content that hasn't been submitted or published anywhere else. | ||
|
||
Read the [blog guidelines](/docs/contribute/blog/guidelines/#what-we-publish) for more about that aspect. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are two official Kubernetes blogs, and the CNCF has [its own blog](https://www.cncf.io/blog/) where you can cover Kubernetes too. | |
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. | |
With only a few special case exceptions, we only publish content that hasn't been submitted or published anywhere else. | |
Read the [blog guidelines](/docs/contribute/blog/guidelines/#what-we-publish) for more about that aspect. | |
This page describes the official Kubernetes blogs, including what each blog covers, how the project maintains published content, and how to contribute to the blogs. This page doesn't describe the | |
[CNCF blog]((https://www.cncf.io/blog/) , where you can also cover Kubernetes. |
This page's intro should ideally introduce the reader to what the page covers. Move the info about what we publish in the main blog to that section below.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually, the main blog section says it in a different way already, so no need to move it down there
If you are not already familiar, you should read up on the differences between the | ||
[main blog](/docs/contribute/blog/#main-blog) and the | ||
[contributor blog](/docs/contribute/blog/#contributor-blog). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use one link to this destination.
[main blog](/docs/contribute/blog/#main-blog) and the | ||
[contributor blog](/docs/contribute/blog/#contributor-blog). | ||
|
||
Some articles appear on both blogs: there is a primary version of the article, and |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add some information in brief about the point of the current page, like "This page describes the criteria for mirroring and how to mirror an article that you're drafting"
For example: if the target audience are Kubernetes contributors only, then the | ||
[contributor blog](/docs/contribute/blog/#contributor-blog). | ||
may be more appropriate; | ||
if the blog post is about open source in general then it may be more suitable on another site outside the Kubernetes project. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This might be too much detail. Consider just telling the reader to ensure that their content is appropriate for our blogs and is being added to the most relevant of the two blogs. Then, link to the "What we publish" section in the blog guidelines for more details.
This consideration about target audience applies to original and mirrored articles equally. | ||
|
||
The Kubernetes project is willing to mirror any blog article that was published to https://kubernetes.dev/blog/ | ||
(the contributor blog), provided that: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
provided that (all of the | any of the) following criteria apply:
880b526
to
40e9b69
Compare
I propose dropping the lazy consensus hold after KubeCon EU 2025. |
Add a dedicated section about contributing to the Kubernetes official blogs. Co-authored-by: Graziano Casto <[email protected]> Co-authored-by: Natali Vlatko <[email protected]> Co-authored-by: Ryota <[email protected]> Co-authored-by: Shannon Kularathna <[email protected]>
40e9b69
to
aa361dd
Compare
Add a dedicated section about contributing to the Kubernetes official blogs.
preview