Merge pull request #50092 from sftim/20250313_blog_contribution
Add guide to blog contributionspull/50424/head
Kubernetes Prow Robot
GitHub
commit
60a4df7d99
|
|
@ -14,16 +14,18 @@ card:
|
|||
<!-- overview -->
|
||||
|
||||
There are lots of ways to contribute to Kubernetes. You can work on designs for new features,
|
||||
you can document the code we already have, you can write for our [blog](/blog). There's more:
|
||||
you can implement those new features or fix bugs. You can help people join our contributor
|
||||
community, or support existing contributors.
|
||||
you can document the code we already have, you can [write for our blogs](/docs/contribute/blog/).
|
||||
There's more: you can implement those new features or fix bugs. You can help people join our
|
||||
contributor community, or support existing contributors.
|
||||
|
||||
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
|
||||
[Contribute to Kubernetes documentation](/docs/contribute/docs/).
|
||||
If you specifically want to learn about contributing to the documentation or
|
||||
other parts of _this_ website, read [Contribute to Kubernetes documentation](/docs/contribute/docs/).
|
||||
If you specifically want to help with the official Kubernetes blogs, read
|
||||
[Contributing to Kubernetes blogs](/docs/contribute/blog/).
|
||||
|
||||
You can also read the
|
||||
{{< glossary_tooltip text="CNCF" term_id="cncf" >}}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
title: Contributing to Kubernetes blogs
|
||||
slug: blog-contribution
|
||||
content_type: concept
|
||||
weight: 15
|
||||
simple_list: true
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
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.
|
||||
|
||||
## Official Kubernetes blogs
|
||||
|
||||
### Main blog
|
||||
|
||||
The main [Kubernetes blog](/blog/) is used by the project to communicate new features, community reports, and any
|
||||
news that might be relevant to the Kubernetes community. This includes end users and developers.
|
||||
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. With only a few special case exceptions, we only publish content that hasn't been submitted or published anywhere else.
|
||||
|
||||
### Contributor blog
|
||||
|
||||
The [Kubernetes contributor blog](https://k8s.dev/blog/) is aimed at an audience of people who
|
||||
work **on** Kubernetes more than people who work **with** Kubernetes. The Kubernetes project
|
||||
deliberately publishes some articles to both blogs.
|
||||
|
||||
Anyone can write a blog post and submit it for review.
|
||||
|
||||
## Article updates and maintenance {#maintenance}
|
||||
|
||||
The Kubernetes project does not maintain older articles for its blogs. This means that any
|
||||
published article more than one year old will normally **not** be eligible for issues or pull
|
||||
requests that ask for changes. To avoid establishing precedent, even technically correct pull
|
||||
requests are likely to be rejected.
|
||||
|
||||
However, there are exceptions like the following:
|
||||
|
||||
* (updates to) articles marked as [evergreen](#maintenance-evergreen)
|
||||
* removing or correcting articles giving advice that is now wrong and dangerous to follow
|
||||
* fixes to ensure that an existing article still renders correctly
|
||||
|
||||
For any article that is over a year old and not marked as _evergreen_, the website automatically
|
||||
displays a notice that the content may be stale.
|
||||
|
||||
### Evergreen articles {#maintenance-evergreen}
|
||||
|
||||
You can mark an article as evergreen by setting `evergreen: true` in the front matter.
|
||||
|
||||
We only mark blog articles as maintained (`evergreen: true` in front matter) if the Kubernetes project
|
||||
can commit to maintaining them indefinitely. Some blog articles absolutely merit this; for example, the release comms team always marks official release announcements as evergreen.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* Discover the official blogs:
|
||||
* [Kubernetes blog](/blog/)
|
||||
* [Kubernetes contributor blog](https://k8s.dev/blog/)
|
||||
|
||||
* Read about [reviewing blog pull requests](/docs/contribute/review/reviewing-prs/#blog)
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
title: Helping as a blog writing buddy
|
||||
slug: writing-buddy
|
||||
content_type: concept
|
||||
weight: 70
|
||||
---
|
||||
|
||||
<!-- 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.
|
||||
|
||||
When people contributor to either blog as an author, the Kubernetes project pairs up authors
|
||||
as _writing buddies_. This page explains how to fulfil the buddy role.
|
||||
|
||||
You should make sure that you have at least read an outline of [article submission](/docs/contribute/blog/submission/)
|
||||
before you read on within this page.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Buddy responsibilities
|
||||
|
||||
As a writing buddy, you:
|
||||
|
||||
* help the blog team get articles ready to merge and to publish
|
||||
* support your buddy to produce content that is good to merge
|
||||
* provide a review on the article that your buddy has written
|
||||
|
||||
|
||||
When the team pairs you up with another author, the idea is that you both support each other by
|
||||
reviewing the other author's draft article.
|
||||
Most people reading articles on the Kubernetes blog are not experts; the content should
|
||||
try to make sense for that audience, or at least to support non-expert readers appropriately.
|
||||
|
||||
The blog team are also there to help you both along the journey from draft to publication.
|
||||
They will either be directly able to approve your article for publication, or can arrange for
|
||||
the approval to happen.
|
||||
|
||||
## Supporting the blog team
|
||||
|
||||
Your main responsibility here is to communicate about your capacity, availability and progress
|
||||
in a reasonable timeline. If many weeks go by and your buddy hasn't heard from you, it makes
|
||||
the overall work take more time.
|
||||
|
||||
## Supporting your buddy
|
||||
|
||||
There are two parts to the process
|
||||
|
||||
{{< tabs name="buddy_support" >}}
|
||||
{{% tab name="Collaborative editing" %}}
|
||||
**(This is the recommended option)**
|
||||
|
||||
The blog team recommend that the main author for the article sets up collaborative editing
|
||||
using either a Google Doc or HackMD (their choice). The main author then shares that document
|
||||
with the following people:
|
||||
|
||||
* Any co-authors
|
||||
* You (their writing buddy)
|
||||
* Ideally, with a nominated
|
||||
person from the blog team.
|
||||
|
||||
As a writing buddy, you then read the draft text and either directly make suggestions or provide
|
||||
feedback in a different way. The author of the blog is very commonly also **your** writing buddy in turn, so they will provide the
|
||||
same kind of feedback on the draft for your blog article.
|
||||
|
||||
Your role here is to recommend the smallest set of changes that will get the article look good
|
||||
for publication. If there's a diagram that really doesn't make sense, or the writing is really
|
||||
unclear: provide feedback. If you have a slight different of opinion about wording or punctuation,
|
||||
skip it. Let the article author(s) write in their own style, provided that they align to
|
||||
the [blog guidelines](/docs/contribute/blog/guidelines/).
|
||||
|
||||
After this is ready, the lead author will open a pull request and use Markdown to submit the
|
||||
article. You then provide a [review](#pull-request-review).
|
||||
{{% /tab %}}
|
||||
{{% tab name="Markdown / Git editing" %}}
|
||||
Some authors prefer to start with
|
||||
[collaborative editing](#buddy-support-0); others like to go straight into
|
||||
GitHub.
|
||||
|
||||
Whichever route they take, your role is to provide feedback that lets the blog team provide
|
||||
a simple signoff and confirm that the article can merge as a draft. See
|
||||
[submitting articles to Kubernetes blogs](/docs/contribute/blog/submission/) for what the authors
|
||||
need to do.
|
||||
|
||||
Use GitHub suggestions to point out any required changes.
|
||||
|
||||
Once the Markdown and other content (such as images) look right, you provide a
|
||||
formal [review](#pull-request-review).
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
|
||||
## Pull request review
|
||||
|
||||
Follow the [blog](/docs/contribute/review/reviewing-prs/#blog) section of _Reviewing pull requests_.
|
||||
|
||||
When you think that the open blog pull request is good enough to merge, add the `/lgtm` comment to the pull request.
|
||||
|
||||
This indicates to the repository automation tooling (Prow) that the content "looks good to me". Prow moves things forward. The `/lgtm` command lets you add your opinion to the record whether or not you are formally a member of the Kubernetes project.
|
||||
|
||||
Either you or the article author(s) should let the blog team know that there is an article
|
||||
ready for signoff. It should already be marked as `draft: true` in the front matter, as
|
||||
explained in the submission guidance.
|
||||
|
||||
## Subsequent steps
|
||||
|
||||
For you as a writing buddy, **there is no step four**. Once the pull request is good to merge,
|
||||
the blog team (or, for the contributor site, the contributor comms team) take things from there.
|
||||
It's possible that you'll need to return to an earlier step based on feedback, but you can usually expect that your work as a buddy is done.
|
||||
|
|
@ -0,0 +1,169 @@
|
|||
---
|
||||
title: Blog guidelines
|
||||
content_type: concept
|
||||
weight: 40
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
These guidelines cover the main Kubernetes blog and the Kubernetes
|
||||
contributor blog.
|
||||
|
||||
All blog content must also adhere to the overall policy in the
|
||||
[content guide](/docs/contribute/style/content-guide/).
|
||||
|
||||
# {{% heading "prerequisites" %}}
|
||||
|
||||
Make sure you are familiar with the introduction sections of
|
||||
[contributing to Kubernetes blogs](/docs/contribute/blog/), not just to learn about
|
||||
the two official blogs and the differences between them, but also to get an overview
|
||||
of the process.
|
||||
|
||||
## Original content
|
||||
|
||||
The Kubernetes project accepts **original content only**, in English.
|
||||
|
||||
{{< note >}}
|
||||
The Kubernetes project cannot accept content for the blog if it has already been submitted
|
||||
or published outside of the Kubernetes project.
|
||||
|
||||
The official blogs are not available as a medium to repurpose existing content from any third
|
||||
party as new content.
|
||||
{{< /note >}}
|
||||
|
||||
This restriction even carries across to promoting other Linux Foundation and CNCF projects.
|
||||
Many CNCF projects have their own blog. These are often a better choice for posts about a specific
|
||||
project, even if that other project is designed specifically to work with Kubernetes (or with Linux,
|
||||
etc).
|
||||
|
||||
## Relevant content
|
||||
|
||||
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.
|
||||
For articles submitted to the main blog that are not
|
||||
[mirror articles](/docs/contribute/blog/mirroring/), hyperlinks in the article should commonly
|
||||
be to the official Kubernetes documentation. When making external references, links should be
|
||||
diverse - for example, a submission shouldn't contain only links back to a single company's blog.
|
||||
|
||||
The official Kubernetes blogs are **not** the place for vendor pitches or for articles that promote
|
||||
a specific solution from outside Kubernetes.
|
||||
|
||||
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.
|
||||
|
||||
The [content guide](/docs/contribute/style/content-guide/) applies unconditionally to blog articles
|
||||
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.
|
||||
|
||||
## Localization
|
||||
|
||||
The website is localized into many languages; English is the “upstream” for all the other
|
||||
localizations. Even if you speak another language and would be happy to provide a localization,
|
||||
that should be in a separate pull request (see [languages per PR](/docs/contribute/new-content/#languages-per-pr)).
|
||||
|
||||
## Copyright and reuse
|
||||
|
||||
You must write [original content](#original-content) and you must have permission to license
|
||||
that content to the Cloud Native Computing Foundation (so that the Kubernetes project can
|
||||
legally publish it).
|
||||
This means that not only is direct plagiarism forbidden, you cannot write a blog article if
|
||||
you don't have permission to meet the CNCF copyright license conditions (for example, if your
|
||||
employer has a policy about intellectual property that restricts what you are allowed to do).
|
||||
|
||||
The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows
|
||||
commercial use of the content for commercial purposes, but not the other way around.
|
||||
|
||||
## Special interest groups and working groups
|
||||
|
||||
Topics related to participation in or results of Kubernetes SIG activities are always on
|
||||
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)
|
||||
for support on these posts).
|
||||
|
||||
The project typically [mirrors](/docs/contribute/blog/mirroring/) these articles to both blogs.
|
||||
|
||||
|
||||
## National restrictions on content
|
||||
|
||||
The Kubernetes website has an Internet Content Provider (ICP) licence from the government of China. Although it's unlikely to be a problem, Kubernetes cannot publish articles that would be blocked by the Chinese government's official filtering of internet content.
|
||||
|
||||
## Blog-specific content guidance {#what-we-publish}
|
||||
|
||||
As well as the general [style guide](/docs/contribute/style/style-guide/), blog articles should (not must) align to
|
||||
the [blog-specific style recommendations](/docs/contribute/blog/article-submission/#article-content).
|
||||
|
||||
The remainder of this page is additional guidance; these are not strict rules that articles
|
||||
must follow, but reviewers are likely to (and should) ask for edits to articles that are
|
||||
obviously not aligned with the recommendations here.
|
||||
|
||||
### Diagrams and illustrations {#illustrations}
|
||||
|
||||
For [illustrations](/docs/contribute/blog/article-submission/#illustrations) - including diagrams or charts - use the [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure)
|
||||
where feasible. You should set an `alt` attribute for accessibility.
|
||||
|
||||
Use vector images for illustrations, technical diagrams and similar graphics; SVG format is recommended as a strong preference.
|
||||
|
||||
Articles that use raster images for illustrations are more difficult to maintain and in some
|
||||
cases the blog team may ask authors to revise the article before it could be published.
|
||||
|
||||
### Timelessness
|
||||
|
||||
Blog posts should aim to be future proof
|
||||
|
||||
- Given the development velocity of the project, SIG Docs prefers _timeless_ writing: content that
|
||||
won't require updates to stay accurate for the reader.
|
||||
- It can be a better choice to add a tutorial or update official documentation than to write a
|
||||
high level overview as a blog post.
|
||||
- Consider concentrating the long technical content as a call to action of the blog post, and
|
||||
focus on the problem space or why readers should care.
|
||||
|
||||
|
||||
### Content examples
|
||||
|
||||
Here are some examples of content that is appropriate for the
|
||||
[main Kubernetes blog](/docs/contribute/blog/#main-blog):
|
||||
|
||||
* Announcements about new Kubernetes capabilities
|
||||
* Explanations of how to achieve an outcome using Kubernetes; for example, tell us about your
|
||||
low-toil improvement on the basic idea of a rolling deploy
|
||||
* Comparisons of several different software options that have a link to Kubernetes and cloud native. It's
|
||||
OK to have a link to one of these options so long as you fully disclose your conflict of
|
||||
interest / relationship.
|
||||
* Stories about problems or incidents, and how you resolved them
|
||||
* Articles discussing building a cloud native platform for specific use cases
|
||||
* Your opinion about the good or bad points about Kubernetes
|
||||
* Announcements and stories about non-core Kubernetes, such as the Gateway API
|
||||
* [Post-release announcements and updates](#post-release-comms)
|
||||
* Messages about important Kubernetes security vulnerabilities
|
||||
* Kubernetes projects updates
|
||||
* Tutorials and walkthroughs
|
||||
* Thought leadership around Kubernetes and cloud native
|
||||
* The components of Kubernetes are purposely modular, so writing about existing integration
|
||||
points like CNI and CSI are on topic. Provided you don't write a vendor pitch, you can also write
|
||||
about what is on the other end of these integrations.
|
||||
|
||||
|
||||
Here are some examples of content that is appropriate for the Kubernetes
|
||||
[contributor blog](/docs/contribute/blog/#contributor-blog):
|
||||
|
||||
* articles about how to test your change to Kubernetes code
|
||||
* content around non-code contribution
|
||||
* discussions about alpha features where the design is still under discussion
|
||||
* "Meet the team" articles about working groups, special interest groups, etc.
|
||||
* a guide about how to write secure code that will become part of Kubernetes itself
|
||||
* articles about maintainer summits and the outcome of those summits
|
||||
|
||||
### Examples of content that wouldn't be accepted {#what-we-do-not-publish}
|
||||
|
||||
However, the project will not publish:
|
||||
|
||||
* vendor pitches
|
||||
* an article you've published elsewhere, even if only to your own low-traffic blog
|
||||
* large chunks of example source code with only a minimal explanation
|
||||
* updates about an external project that works with our relies on Kubernetes (put those on
|
||||
the external project's own blog)
|
||||
* articles about using Kubernetes with a specific cloud provider
|
||||
* articles that criticise specific people, groups of people, or businesses
|
||||
* articles that have important technical mistakes or misleading details (for example: if you
|
||||
recommend turning off an important security control in production clusters, because it can
|
||||
be inconvenient, the Kubernetes project is likely to reject the article).
|
||||
|
||||
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: Blog article mirroring
|
||||
slug: article-mirroring
|
||||
content_type: concept
|
||||
weight: 50
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
There are two official Kubernetes blogs, and the CNCF has its own 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.
|
||||
|
||||
Some articles appear on both blogs: there is a primary version of the article, and
|
||||
a _mirror article_ on the other blog.
|
||||
|
||||
This page describes the criteria for mirroring, the motivation for mirroring, and
|
||||
explains what you should do to ensure that an article publishes to both blogs.
|
||||
|
||||
# {{% heading "prerequisites" %}}
|
||||
|
||||
Make sure you are familiar with the introduction sections of
|
||||
[contributing to Kubernetes blogs](/docs/contribute/blog/), not just to learn about
|
||||
the two official blogs and the differences between them, but also to get an overview
|
||||
of the process.
|
||||
|
||||
<!-- content -->
|
||||
|
||||
## Why we mirror
|
||||
|
||||
Mirroring is nearly always from the contributor blog to the main blog. The project does this
|
||||
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 blog](/docs/contribute/blog/#main-blog).
|
||||
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.
|
||||
|
||||
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 all of the following criteria are met:
|
||||
|
||||
- the mirrored article has the same publication date as the original (it should have the same publication time too,
|
||||
but you can also set a time stamp up to 12 hours later for special cases)
|
||||
|
||||
- For PRs that add a mirrored article to the main blog *after* the original article has merged into the contributor blog, ensure that all of the following criteria are met:
|
||||
- No articles were published to the main blog after the original article was published to the contributor blog.
|
||||
- There are no main blog articles scheduled for publication between the publication time of the original article and the publication time of your mirrored article.
|
||||
|
||||
This is because the Kubernetes project doesn't want to add articles to people's feeds, such as RSS, except at the very end of their feed.
|
||||
|
||||
- the original article doesn't contravene any strongly recommended review guidelines or community norms
|
||||
|
||||
- the mirrored article will have `canonicalUrl` set correctly in its
|
||||
[front matter](https://gohugo.io/content-management/front-matter/)
|
||||
|
||||
- the audience for the original article would find it relevant
|
||||
|
||||
- the article content is not off-topic for the target blog where the mirror article would
|
||||
appear
|
||||
|
||||
|
||||
Mirroring from the main blog to the contributor blog is rare, but could feasibly happen.
|
||||
|
||||
## How to mirror
|
||||
|
||||
You make a PR against the other Git repository (usually,
|
||||
[https://github.com/kubernetes/website](https://github.com/kubernetes/website)) that adds
|
||||
the article. You do this _before_ the articles merge.
|
||||
|
||||
As the article author, you should set the canonical URL for the mirrored article, to the URL of the original article
|
||||
(you can use a preview to predict the URL and fill this in ahead of actual publication). Use the `canonicalUrl`
|
||||
field in [front matter](https://gohugo.io/content-management/front-matter/) for this.
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
title: Post-release communications
|
||||
content_type: concept
|
||||
weight: 60
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
The Kubernetes _Release Comms_ team (part of
|
||||
[SIG Release](https://github.com/kubernetes/community/tree/master/sig-release))
|
||||
looks after release announcements, which go onto the
|
||||
[main project blog](/docs/contribute/blog/#main-blog).
|
||||
|
||||
After each release, the Release Comms team take over the main blog for a period
|
||||
and publish a series of additional articles to explain or announce changes related to
|
||||
that release. These additional articles are termed _post-release comms_.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Opting in to post-release comms {#opt-in}
|
||||
|
||||
During a release cycle, as a contributor, you can opt in to post-release comms about an
|
||||
upcoming change to Kubernetes.
|
||||
|
||||
To opt in you open a draft, _placeholder_ [pull request](https://www.k8s.dev/docs/guide/pull-requests/) (PR)
|
||||
against [k/website](https://github.com/kubernetes/website). Initially, this can be an
|
||||
empty commit. Mention the KEP issue or other Kubernetes improvement issue in the description
|
||||
of your placeholder PR.
|
||||
|
||||
When you open the **draft** pull request, you open it against _main_ as the base branch
|
||||
and not against the `dev-{{< skew nextMinorVersion >}}` branch. This is different from
|
||||
the [process](/docs/contribute/new-content/new-features/#open-a-placeholder-pr) for upcoming release changes and new features.
|
||||
|
||||
You should also leave a comment on the related [kubernetes/enhancements](https://github.com/kubernetes/enhancements)
|
||||
issue with a link to the PR to notify the Release Comms team managing this release. Your comment
|
||||
helps the team see that the change needs announcing and that your SIG has opted in.
|
||||
|
||||
As well as the above, you should ideally contact the Release Comms team via Slack
|
||||
(channel [`#release-comms`](https://kubernetes.slack.com/archives/CNT9Y603D)) to let them
|
||||
know that you have done this and would like to opt in.
|
||||
|
||||
## Preparing the article content {#preparation}
|
||||
|
||||
You should follow the usual [article submission](/docs/contribute/blog/article-submission/)
|
||||
process to turn your placeholder PR into something ready for review. However, for
|
||||
post-release comms, you may not have a _writing buddy_; instead, the Release Comms team
|
||||
may assign a member of the team to help guide what you're doing.
|
||||
|
||||
You should [squash](https://www.k8s.dev/docs/guide/pull-requests/#squashing) the commits
|
||||
in your pull request; if you're not sure how to, it's absolutely OK to ask Release Comms or
|
||||
the blog team for help.
|
||||
|
||||
Provided that your article is flagged as a draft (`draft: true`) in the
|
||||
[front matter](https://gohugo.io/content-management/front-matter/), the PR can merge at any
|
||||
time during the release cycle.
|
||||
|
||||
## Publication
|
||||
|
||||
Ahead of the actual release, the Release Comms team check what content is ready (if it's
|
||||
not ready by the deadline, and you didn't get an exception, then the announcement won't
|
||||
be included). They build a schedule for the articles that will go out and open new
|
||||
pull requests to turn those articles from draft to published.
|
||||
|
||||
{{< caution >}}
|
||||
All these pull requests to actually publish post-release articles **must** be held
|
||||
(Prow command `/hold`) until the release has actually happened.
|
||||
{{< /caution >}}
|
||||
|
||||
The blog team approvers still provide final sign off on promoting the content from draft
|
||||
to accepted for publication. Ahead of release day, the PR (or PRs) for publishing these
|
||||
announcements should have LGTM (“looks good to me”) and approved labels, along with the
|
||||
**do-not-merge/hold** label to ensure the PR doesn't merge too early.
|
||||
|
||||
Release Comms / the Release Team can then _unhold_ that PR (or set of PRs) as soon as the
|
||||
website Git repository is unfrozen after the actual release.
|
||||
|
||||
On the day each article is scheduled to publish, automation triggers a website build and that
|
||||
article becomes visible.
|
||||
|
|
@ -0,0 +1,232 @@
|
|||
---
|
||||
title: Submitting articles to Kubernetes blogs
|
||||
slug: article-submission
|
||||
content_type: concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
There are two official Kubernetes blogs, and the CNCF has its own blog where you can cover Kubernetes too.
|
||||
For the [main Kubernetes blog](/docs/contribute/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.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Writing for the Kubernetes blog(s)
|
||||
|
||||
As an author, you have three different routes towards publication.
|
||||
|
||||
### Recommended route {#route-1}
|
||||
|
||||
The approach the Kubernetes project recommends is: pitch your article by contacting the blog team. You can do that via Kubernetes Slack ([#sig-docs-blog](https://kubernetes.slack.com/archives/CJDHVD54J)).
|
||||
For articles that you want to publish to the contributor blog only, you can also pitch directly
|
||||
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:
|
||||
|
||||
* a blog _editor_
|
||||
* your _writing buddy_ (another blog author)
|
||||
|
||||
When the team pairs you up with another author, the idea is that you both support each other by
|
||||
reviewing the other author's draft article. You don't need to be a subject matter expert; most of
|
||||
the people who read the article also won't be experts. We, the Kubernetes blog team, call the other author a writing buddy.
|
||||
|
||||
The editor is there to help you along the journey from draft to publication. They will either be
|
||||
directly able to approve your article for publication, or can arrange for the approval to happen.
|
||||
|
||||
Read [authoring a blog article](#authoring) to learn more about the process.
|
||||
|
||||
### Starting with a pull request {#route-2}
|
||||
|
||||
The second route to writing for our blogs is to start directly with a pull request in GitHub. The
|
||||
blog team actually don't recommend this; GitHub is quite useful for collaborating on code,
|
||||
but isn't an ideal fit for prose text.
|
||||
|
||||
It's absolutely fine to open a placeholder pull request with just an empty commit, and then
|
||||
work elsewhere before returning to your placeholder PR.
|
||||
|
||||
Similar to the [recommended route](#route-1), we'll try to pair you up with a writing buddy
|
||||
and a blog editor. They'll help you get the article ready for publication.
|
||||
|
||||
### Post-release blog article process {#route-3-post-release-comms}
|
||||
|
||||
The third route is for blog articles about changes in Kubernetes relating to a release. Each
|
||||
time there is a release, the Release Comms team takes over the blog publication schedule. People
|
||||
adding features to a release, or who are planning other changes that the project needs to announce, can
|
||||
liaise with Release Comms to get their article planned, drafted, edited, and eventually published.
|
||||
|
||||
## Article scheduling
|
||||
|
||||
For the Kubernetes blog, the blog team usually schedules blog articles to publish on weekdays
|
||||
(Gregorian calendar, as used in the USA and other countries). When it's important to publish on
|
||||
a specific date that falls on a weekend, the blog team try to accommodate that.
|
||||
|
||||
The section on [authoring a blog article]{#authoring} explains what to do:
|
||||
|
||||
* initially, don't specify a date for the article
|
||||
* however, do set the article as draft (put `draft: true` in the front matter)
|
||||
|
||||
When the Prow bot merges the PR you write, it will be a draft and won't be set to publish. A
|
||||
Kubernetes contributor (either you, your writing buddy or someone from the blog team) then opens a small
|
||||
follow-up PR that marks it for publication. Merging that second PR releases the previously-draft
|
||||
article so that it can automatically publish.
|
||||
|
||||
On the day the article is scheduled to publish, automation triggers a website build and your
|
||||
article becomes visible.
|
||||
|
||||
|
||||
## 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 read your
|
||||
draft text and then either directly make suggestions or provide other feedback. They should
|
||||
also let you know if what you're drafting feedback isn't in line with the
|
||||
[blog guidelines](/docs/contribute/blog/guidelines/).
|
||||
|
||||
At the same time, you'll normally be **their** writing buddy and can follow our
|
||||
[guide](/docs/contribute/blog/writing-buddy/) about supporting their work.
|
||||
|
||||
### Initial administrative steps
|
||||
|
||||
You should [sign the CLA](/docs/contribute/new-content/#contributing-basics)
|
||||
if you have not yet done so. It is best to make sure you start this early on; if you are
|
||||
writing as part of your job, you may need to check with the workplace legal team or with
|
||||
your manager, to make sure that you are allowed to sign.
|
||||
|
||||
### Initial drafting
|
||||
|
||||
The blog team recommends that you either use HackMD (a web Markdown editor) or a
|
||||
Google doc, to prepare and share an initial, live-editable version of the article text.
|
||||
|
||||
{{< note >}}
|
||||
If you choose to use Google Docs, you can set your document into Markdown mode.
|
||||
{{< /note >}}
|
||||
|
||||
Your writing buddy can provide comments and / or feedback for your draft text and
|
||||
will (or should) check that it's in line with the guidelines. At the same time, you'll
|
||||
be their writing buddy and can follow the [guide](/docs/contribute/blog/editing/#writing-buddies)
|
||||
that explains how you'll be supporting their work.
|
||||
|
||||
Don't worry too much at this stage about getting the Markdown formatting exactly right, though.
|
||||
|
||||
If you have images, you can paste in a bitmap copy for early feedback. The blog team can help
|
||||
you (later in the process), to get illustrations ready for final publication.
|
||||
|
||||
### Markdown for publication
|
||||
|
||||
Have a look at the Markdown format for existing blog posts in the
|
||||
[website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts)
|
||||
in GitHub.
|
||||
|
||||
If you're not already familiar, read [contributing basics](/docs/contribute/new-content/#contributing-basics).
|
||||
This section of the page assumes that you don't have a local clone of your fork and that you
|
||||
are working within the GitHub web UI.
|
||||
You do need to make a remote fork of the website repository if you haven't already done so.
|
||||
|
||||
In the GitHub repository, click the **Create new file** button. Copy your existing content
|
||||
from HackMD or Google Docs, then paste it into the editor.
|
||||
There are more details later in the section about what goes into that file.
|
||||
Name the file to match the proposed title of the blog post, but don’t put the date in the file name.
|
||||
The blog reviewers will work with you to set the final file name and the date when the article will be published.
|
||||
|
||||
1. When you save the file, GitHub will walk you through the pull request process.
|
||||
|
||||
1. Your writing buddy can review your submission and work with you on feedback and final details.
|
||||
A blog editor approves your pull request to merge, as a draft that is not yet scheduled.
|
||||
|
||||
#### Front matter
|
||||
|
||||
The Markdown file you write should use YAML-format Hugo
|
||||
[front matter](https://gohugo.io/content-management/front-matter/).
|
||||
|
||||
Here's an example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
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)
|
||||
---
|
||||
```
|
||||
|
||||
* initially, don't specify a date for the article
|
||||
* however, do set the article as draft (put `draft: true` in the
|
||||
article [front matter](https://gohugo.io/content-management/front-matter/))
|
||||
|
||||
#### Article content
|
||||
|
||||
Make sure to use second-level Markdown headings (`##` not `#`) as the topmost heading level in
|
||||
the article. The `title` you set in the front matter becomes the first-level heading for that
|
||||
page.
|
||||
|
||||
You should follow the [style guide](https://kubernetes.io/docs/contribute/style/style-guide/),
|
||||
but with the following exceptions:
|
||||
|
||||
- we are OK to have authors write an article in their own writing style, so long as most readers
|
||||
would follow the point being made
|
||||
- it is OK to use “we“ in a blog article that has multiple authors, or where the article introduction clearly indicates that the author is writing on behalf of a specific group.
|
||||
As you'll notice from this section, although we [avoid using “we”](/docs/contribute/style/style-guide/#avoid-using-we) in our documentation,
|
||||
it's OK to make justifiable exceptions.
|
||||
- we avoid using Kubernetes shortcodes for callouts (such as `{{</* caution */>}}`). This is
|
||||
because callouts are aimed at documentation readers, and blog articles aren't documentation.
|
||||
- statements about the future are OK, albeit we use them with care in official announcements on
|
||||
behalf of Kubernetes
|
||||
- code samples used in blog articles don't need to use the `{{</* code_sample */>}}` shortcode, and often
|
||||
it is better (easier to maintain) if they do not
|
||||
|
||||
#### Diagrams and illustrations {#illustrations}
|
||||
|
||||
For illustrations, diagrams or charts, use the [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure) can be used where feasible. You should set an `alt` attribute for accessibility.
|
||||
|
||||
For illustrations and technical diagrams, try to use vector graphics. The blog team recommend SVG over raster (bitmap / pixel)
|
||||
diagram formats, and also recommend SVG rather than Mermaid (you can still capture the Mermaid source in a comment).
|
||||
The preference for SVG over Mermaid is because when maintainers upgrade Mermaid or make changes to diagram rendering, they may not have an easy way to contact the original blog article author to check that the changes are OK.
|
||||
|
||||
The [diagram guide](/docs/contribute/style/diagram-guide/) is aimed at Kubernetes documentation,
|
||||
not blog articles. It is still good to align with it but:
|
||||
- there is no need to caption diagrams as Figure 1, Figure 2, etc.
|
||||
|
||||
The requirement for scalable (vector) imanges makes the process more difficult for
|
||||
less-familiar folks to submit articles; Kubernetes SIG Docs continues to look for ways to
|
||||
lower this bar.
|
||||
If you have ideas on how to lower the barrier, please volunteer to help out.
|
||||
|
||||
<!-- note to maintainers of this page: vector images are easier to localize and
|
||||
are resolution independent, so can look consistently good on different screens -->
|
||||
|
||||
For other images (such as photos), the blog team strongly encourages use of `alt` attributes.
|
||||
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
|
||||
|
||||
At the point you mark your pull request ready for review, each commit message should be a
|
||||
short summary of the work being done. The first commit message should make sense as an overall
|
||||
description of the blog post.
|
||||
|
||||
Examples of a good commit message:
|
||||
|
||||
- _Add blog post on the foo kubernetes feature_
|
||||
- _blog: foobar announcement_
|
||||
|
||||
Examples of bad commit messages:
|
||||
|
||||
- _Placeholder commit for announcement about foo_
|
||||
- _Add blog post_
|
||||
- _asdf_
|
||||
- _initial commit_
|
||||
- _draft post_
|
||||
|
||||
#### Squashing
|
||||
|
||||
Once you think the article is ready to merge, you should
|
||||
[squash](https://www.k8s.dev/docs/guide/pull-requests/#squashing) the commits in your pull
|
||||
request; if you're not sure how to, it's OK to ask the blog team for help.
|
||||
|
|
@ -19,6 +19,9 @@ Kubernetes documentation contributors:
|
|||
- Translate the documentation
|
||||
- Manage and publish the documentation parts of the Kubernetes release cycle
|
||||
|
||||
The blog team, part of SIG Docs, helps manage the official blogs. Read
|
||||
[contributing to Kubernetes blogs](/docs/contribute/blog/) to learn more.
|
||||
|
||||
---
|
||||
|
||||
{{< note >}}
|
||||
|
|
@ -200,4 +203,5 @@ SIG Docs communicates with different methods:
|
|||
to get involved with Kubernetes feature development.
|
||||
- Visit the contributor site to learn more about [Kubernetes Contributors](https://www.kubernetes.dev/)
|
||||
and [additional contributor resources](https://www.kubernetes.dev/resources/).
|
||||
- Submit a [blog post or case study](/docs/contribute/new-content/blogs-case-studies/).
|
||||
- Learn how to [contribute to the official blogs](/docs/contribute/blog/)
|
||||
- Submit a [case study](/docs/contribute/new-content/case-studies/)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,8 @@
|
|||
title: Contributing new content
|
||||
content_type: concept
|
||||
main_menu: true
|
||||
weight: 20
|
||||
weight: 25
|
||||
simple_list: true # for whatsnext section
|
||||
---
|
||||
|
||||
|
||||
|
|
@ -10,10 +11,17 @@ weight: 20
|
|||
<!-- overview -->
|
||||
|
||||
This section contains information you should know before contributing new
|
||||
content.
|
||||
content.
|
||||
|
||||
There are also dedicated pages about submitting [case studies](/docs/contribute/new-content/case-studies)
|
||||
and [blog articles](/docs/contribute/blog/).
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## New content task flow
|
||||
|
||||
<!-- See https://github.com/kubernetes/website/issues/28808 for live-editor URL to this figure -->
|
||||
<!-- You can also cut/paste the mermaid code into the live editor at https://mermaid-js.github.io/mermaid-live-editor to play around with it -->
|
||||
|
||||
{{< mermaid >}}
|
||||
flowchart LR
|
||||
subgraph second[Before you begin]
|
||||
|
|
@ -118,3 +126,7 @@ The [doc contributors tools](https://github.com/kubernetes/website/tree/main/con
|
|||
directory in the `kubernetes/website` repository contains tools to help your
|
||||
contribution journey go more smoothly.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!-- relies on simple_list: true in front matter for remaining links -->
|
||||
* Read about submitting [blog articles](/docs/contribute/blog/article-submission/).
|
||||
|
|
|
|||
|
|
@ -1,218 +0,0 @@
|
|||
---
|
||||
title: Submitting blog posts and case studies
|
||||
linktitle: Blogs and case studies
|
||||
slug: blogs-case-studies
|
||||
content_type: concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
Anyone can write a blog post and submit it for review.
|
||||
Case studies require extensive review before they're approved.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## The Kubernetes Blog
|
||||
|
||||
The Kubernetes blog is used by the project to communicate new features, community reports, and any
|
||||
news that might be relevant to the Kubernetes community. This includes end users and developers.
|
||||
Most of the blog's content is about things happening in the core project, but we encourage you to
|
||||
submit about things happening elsewhere in the ecosystem too!
|
||||
|
||||
Anyone can write a blog post and submit it for review.
|
||||
|
||||
### Submit a Post
|
||||
|
||||
Blog posts should not be commercial in nature and should consist of original content that applies
|
||||
broadly to the Kubernetes community. Appropriate blog content includes:
|
||||
|
||||
- New Kubernetes capabilities
|
||||
- Kubernetes projects updates
|
||||
- Updates from Special Interest Groups
|
||||
- Tutorials and walkthroughs
|
||||
- Thought leadership around Kubernetes
|
||||
- Kubernetes Partner OSS integration
|
||||
- **Original content only**
|
||||
|
||||
Unsuitable content includes:
|
||||
|
||||
- Vendor product pitches
|
||||
- Partner updates without an integration and customer story
|
||||
- Syndicated posts (language translations ok)
|
||||
|
||||
To submit a blog post, follow these steps:
|
||||
|
||||
1. [Sign the CLA](https://github.com/kubernetes/community/blob/master/CLA.md)
|
||||
if you have not yet done so.
|
||||
|
||||
1. Have a look at the Markdown format for existing blog posts in the
|
||||
[website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts).
|
||||
|
||||
1. Write out your blog post in a text editor of your choice.
|
||||
|
||||
1. On the same link from step 2, click the Create new file button. Paste your content into the editor.
|
||||
Name the file to match the proposed title of the blog post, but don’t put the date in the file name.
|
||||
The blog reviewers will work with you on the final file name and the date the blog will be published.
|
||||
|
||||
1. When you save the file, GitHub will walk you through the pull request process.
|
||||
|
||||
1. A blog post reviewer will review your submission and work with you on feedback and final details.
|
||||
When the blog post is approved, the blog will be scheduled for publication.
|
||||
|
||||
### Guidelines and expectations
|
||||
|
||||
- Blog posts should not be vendor pitches.
|
||||
|
||||
- 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.
|
||||
Check the [Documentation style guide](/docs/contribute/style/content-guide/#what-s-allowed) for
|
||||
what is typically allowed on Kubernetes properties.
|
||||
- Links 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
|
||||
back to a single company's blog.
|
||||
- Sometimes this is a delicate balance. The [blog team](https://kubernetes.slack.com/messages/sig-docs-blog/)
|
||||
is there to give guidance on whether a post is appropriate for the Kubernetes blog, so don't
|
||||
hesitate to reach out.
|
||||
|
||||
- Blog posts are not published on specific dates.
|
||||
|
||||
- Articles are reviewed by community volunteers. We'll try our best to accommodate specific
|
||||
timing, but we make no guarantees.
|
||||
- Many core parts of the Kubernetes projects submit blog posts during release windows, delaying
|
||||
publication times. Consider submitting during a quieter period of the release cycle.
|
||||
- If you are looking for greater coordination on post release dates, coordinating with
|
||||
[CNCF marketing](https://www.cncf.io/about/contact/) is a more appropriate choice than submitting a blog post.
|
||||
- Sometimes reviews can get backed up. If you feel your review isn't getting the attention it needs,
|
||||
you can reach out to the blog team on the [`#sig-docs-blog` Slack channel](https://kubernetes.slack.com/messages/sig-docs-blog/)
|
||||
to ask in real time.
|
||||
|
||||
- Blog posts should be relevant to Kubernetes users.
|
||||
|
||||
- Topics related to participation in or results of Kubernetes SIGs activities are always on
|
||||
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)
|
||||
for support on these posts).
|
||||
- The components of Kubernetes are purposely modular, so tools that use existing integration
|
||||
points like CNI and CSI are on topic.
|
||||
- Posts about other CNCF projects may or may not be on topic. We recommend asking the blog team
|
||||
before submitting a draft.
|
||||
- Many CNCF projects have their own blog. These are often a better choice for posts. There are
|
||||
times of major feature or milestone for a CNCF project that users would be interested in
|
||||
reading on the Kubernetes blog.
|
||||
- Blog posts about contributing to the Kubernetes project should be in the
|
||||
[Kubernetes Contributors site](https://kubernetes.dev)
|
||||
|
||||
- Blog posts should be original content
|
||||
|
||||
- The official blog is not for repurposing existing content from a third party as new content.
|
||||
- The [license](https://github.com/kubernetes/website/blob/main/LICENSE) for the blog allows
|
||||
commercial use of the content for commercial purposes, but not the other way around.
|
||||
|
||||
- Blog posts should aim to be future proof
|
||||
|
||||
- Given the development velocity of the project, we want evergreen content that won't require
|
||||
updates to stay accurate for the reader.
|
||||
- It can be a better choice to add a tutorial or update official documentation than to write a
|
||||
high level overview as a blog post.
|
||||
- Consider concentrating the long technical content as a call to action of the blog post, and
|
||||
focus on the problem space or why readers should care.
|
||||
|
||||
### Technical Considerations for submitting a blog post
|
||||
|
||||
Submissions need to be in Markdown format to be used by the [Hugo](https://gohugo.io/) generator
|
||||
for the blog. There are [many resources available](https://gohugo.io/documentation/) on how to use
|
||||
this technology stack.
|
||||
|
||||
For illustrations, diagrams or charts, the [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure)
|
||||
can be used. For other images, we strongly encourage use of alt attributes; if an image doesn't
|
||||
need any alt attrribute, maybe it's not needed in the article at all.
|
||||
|
||||
We recognize that this requirement makes the process more difficult for less-familiar folks to
|
||||
submit, and we're constantly looking at solutions to lower this bar. If you have ideas on how to
|
||||
lower the barrier, please volunteer to help out.
|
||||
|
||||
The SIG Docs [blog subproject](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject)
|
||||
manages the review process for blog posts. For more information, see
|
||||
[Submit a post](https://github.com/kubernetes/community/tree/master/sig-docs/blog-subproject#submit-a-post).
|
||||
|
||||
To submit a blog post follow these directions:
|
||||
|
||||
- [Open a pull request](/docs/contribute/new-content/open-a-pr/#fork-the-repo) with a new blog post.
|
||||
New blog posts go under the [`content/en/blog/_posts`](https://github.com/kubernetes/website/tree/main/content/en/blog/_posts)
|
||||
directory.
|
||||
|
||||
- Ensure that your blog post follows the correct naming conventions and the following frontmatter
|
||||
(metadata) information:
|
||||
|
||||
- The Markdown file name must follow the format `YYYY-MM-DD-Your-Title-Here.md`. For example,
|
||||
`2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md`.
|
||||
- Do **not** include dots in the filename. A name like `2020-01-01-whats-new-in-1.19.md` causes
|
||||
failures during a build.
|
||||
- The front matter must include the following:
|
||||
|
||||
```yaml
|
||||
---
|
||||
layout: blog
|
||||
title: "Your Title Here"
|
||||
date: YYYY-MM-DD
|
||||
slug: text-for-URL-link-here-no-spaces
|
||||
author: >
|
||||
Author-1 (Affiliation),
|
||||
Author-2 (Affiliation),
|
||||
Author-3 (Affiliation)
|
||||
---
|
||||
```
|
||||
|
||||
- The first or initial commit message should be a short summary of the work being done and
|
||||
should stand alone as a description of the blog post. Please note that subsequent edits to
|
||||
your blog will be squashed into this main commit, so it should be as useful as possible.
|
||||
|
||||
- Examples of a good commit message:
|
||||
- _Add blog post on the foo kubernetes feature_
|
||||
- _blog: foobar announcement_
|
||||
- Examples of bad commit message:
|
||||
- _Add blog post_
|
||||
- _._
|
||||
- _initial commit_
|
||||
- _draft post_
|
||||
|
||||
- The blog team will then review your PR and give you comments on things you might need to fix.
|
||||
After that the bot will merge your PR and your blog post will be published.
|
||||
|
||||
- If the content of the blog post contains only content that is not expected to require updates
|
||||
to stay accurate for the reader, it can be marked as evergreen and exempted from the automatic
|
||||
warning about outdated content added to blog posts older than one year.
|
||||
|
||||
- To mark a blog post as evergreen, add this to the front matter:
|
||||
|
||||
```yaml
|
||||
evergreen: true
|
||||
```
|
||||
- Examples of content that should not be marked evergreen:
|
||||
- **Tutorials** that only apply to specific releases or versions and not all future versions
|
||||
- References to pre-GA APIs or features
|
||||
|
||||
### Mirroring from the Kubernetes Contributor Blog
|
||||
|
||||
To mirror a blog post from the [Kubernetes contributor blog](https://www.kubernetes.dev/blog/), follow these guidelines:
|
||||
|
||||
- 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.
|
||||
- The mirrored blog should have a `canonicalUrl`, that is, essentially the url of the original blog after it has been published.
|
||||
- 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.
|
||||
- Publication dates stay the same as the original blog.
|
||||
|
||||
All of the other guidelines and expectations detailed above apply as well.
|
||||
|
||||
## Submit a case study
|
||||
|
||||
Case studies highlight how organizations are using Kubernetes to solve real-world problems. The
|
||||
Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}}
|
||||
collaborate with you on all case studies.
|
||||
|
||||
Have a look at the source for the
|
||||
[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies).
|
||||
|
||||
Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md)
|
||||
and submit your request as outlined in the guidelines.
|
||||
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: Submitting case studies
|
||||
linktitle: Case studies
|
||||
slug: case-studies
|
||||
content_type: concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
Case studies highlight how organizations are using Kubernetes to solve real-world problems. The
|
||||
Kubernetes marketing team and members of the {{< glossary_tooltip text="CNCF" term_id="cncf" >}}
|
||||
collaborate with you on all case studies.
|
||||
|
||||
Case studies require extensive review before they're approved.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## Submit a case study
|
||||
|
||||
Have a look at the source for the
|
||||
[existing case studies](https://github.com/kubernetes/website/tree/main/content/en/case-studies).
|
||||
|
||||
Refer to the [case study guidelines](https://github.com/cncf/foundation/blob/master/case-study-guidelines.md)
|
||||
and submit your request as outlined in the guidelines.
|
||||
|
||||
|
|
@ -21,6 +21,9 @@ feature as a pull request to the appropriate development branch of the
|
|||
editorial feedback or edits the draft directly. This section covers the branching
|
||||
conventions and process used during a release by both groups.
|
||||
|
||||
To learn about announcing features on the blog, read
|
||||
[post-release communications](/docs/contribute/blog/release-comms/).
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## For documentation contributors
|
||||
|
|
|
|||
|
|
@ -197,7 +197,12 @@ other dead link issues `/priority important-longterm`, as they must be manually
|
|||
We expect [Kubernetes Blog](/blog/) entries to become
|
||||
outdated over time. Therefore, we only maintain blog entries less than a year old.
|
||||
If an issue is related to a blog entry that is more than one year old,
|
||||
close the issue without fixing.
|
||||
you should typically close the issue without fixing.
|
||||
|
||||
You can send a link to [article updates and maintenance](/docs/contribute/blog/#maintenance)
|
||||
as part of the message you send when you close the PR.
|
||||
|
||||
It is OK to make an exception where a relevant justification applies.
|
||||
|
||||
### Support requests or code bug reports
|
||||
|
||||
|
|
|
|||
|
|
@ -147,7 +147,9 @@ When reviewing, use the following as a starting point.
|
|||
- Does similar content exist elsewhere on the Kubernetes site?
|
||||
- Does the content excessively link to off-site, individual vendor or non-open source documentation?
|
||||
|
||||
### Website
|
||||
### Documentation
|
||||
|
||||
Some checks to consider:
|
||||
|
||||
- Did this PR change or remove a page title, slug/alias or anchor link? If so, are there broken
|
||||
links as a result of this PR? Is there another option, like changing the page title without
|
||||
|
|
@ -165,56 +167,39 @@ 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:
|
||||
- the mirrored article has the same publication date as the original (it should have the same publication time too, but you can also set a time stamp up to 12 hours later for special cases)
|
||||
- for PRs that arrive the original article was merged to https://kubernetes.dev/, there haven't been
|
||||
(and won't be) any articles published to the main blog between time that the original and mirrored article
|
||||
[will] publish.
|
||||
This is because we don't want to add articles to people's feeds, such as RSS, except at the very end of their feed.
|
||||
- the original article doesn't contravene any strongly recommended review guidelines or community norms.
|
||||
- You should set the canonical URL for the mirrored article, to the URL of the original article
|
||||
(you can use a preview to predict the URL and fill this in ahead of actual publication). Use the `canonicalUrl`
|
||||
field in [front matter](https://gohugo.io/content-management/front-matter/) for this.
|
||||
- Consider the target audience and whether the blog post is appropriate for kubernetes.io
|
||||
For example, if the target audience are Kubernetes contributors only then kubernetes.dev
|
||||
may be more appropriate,
|
||||
or if the blog post is on general platform engineering then it may be more suitable on another site.
|
||||
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).
|
||||
|
||||
This consideration applies to mirrored articles too; although we are willing to consider all valid
|
||||
contributor articles for mirroring if a PR is opened, we don't mirror all of them.
|
||||
Before reviewing blog PRs, be familiar with the [blog guidelines](/docs/contribute/blog/guidelines/)
|
||||
and with [submitting blog posts and case studies](/docs/contribute/new-content/blogs-case-studies/).
|
||||
|
||||
- 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, and we
|
||||
always mark our release announcements evergreen. Check with other contributors if you are not sure
|
||||
how to review on this point.
|
||||
- The [content guide](/docs/contribute/style/content-guide/) applies unconditionally to blog articles
|
||||
and the PRs that add them. Bear in mind that some restrictions in the guide state that they are only relevant to documentation; those restrictions don't apply to blog articles.
|
||||
- The [style guide](/docs/contribute/style/style-guide/) largely also applies to blog PRs, but we make some exceptions.
|
||||
|
||||
- it is OK to use “we“ in a blog article that has multiple authors, or where the article introduction clearly indicates that the author is writing on behalf of a specific group.
|
||||
- we avoid using Kubernetes shortcodes for callouts (such as `{{</* caution */>}}`)
|
||||
- statements about the future are OK, albeit we use them with care in official announcements on
|
||||
behalf of Kubernetes
|
||||
- code samples don't need to use the `{{</* code_sample */>}}` shortcode, and often it is better if they do not
|
||||
- we are OK to have authors write an article in their own writing style, so long as most readers
|
||||
would follow the point being made
|
||||
- The [diagram guide](/docs/contribute/style/diagram-guide/) is aimed at Kubernetes documentation,
|
||||
not blog articles. It is still good to align with it but:
|
||||
- we prefer SVG over raster diagram formats, and also over Mermaid (you can still capture the Mermaid source in a comment)
|
||||
- there is no need to caption diagrams as Figure 1, Figure 2 etc
|
||||
Make sure you also know about [evergreen](/docs/contribute/blog/#maintenance-evergreen) articles
|
||||
and how to decide if an article is evergreen.
|
||||
|
||||
Blog articles may contain [direct quotes](https://en.wikipedia.org/wiki/Direct_discourse) and
|
||||
[indirect speech](https://en.wikipedia.org/wiki/Indirect_speech). Avoid suggesting a rewording for
|
||||
anything that is attributed to someone or part of a dialog that has happened - even if you think
|
||||
the original speaker's grammar was not correct. For those cases, also, try to respect the article
|
||||
author's suggested punctuation unless it is obviously wrong.
|
||||
|
||||
As a project, 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, and we always mark our release announcements evergreen. Check with other contributors if you are not sure how to review on this point.
|
||||
|
||||
The [content guide](/docs/contribute/style/content-guide/) applies unconditionally to blog articles and the PRs that add them. Bear in mind that some restrictions in the guide state that they are only relevant to documentation; those restrictions don't apply to blog articles.
|
||||
|
||||
Check if the Markdown source is using the right [page content type](/docs/contribute/style/page-content-types/) and / or `layout`.
|
||||
|
||||
### Other
|
||||
|
||||
- Watch out for [trivial edits](https://www.kubernetes.dev/docs/guide/pull-requests/#trivial-edits);
|
||||
Watch out for [trivial edits](https://www.kubernetes.dev/docs/guide/pull-requests/#trivial-edits);
|
||||
if you see a change that you think is a trivial edit, please point out that policy
|
||||
(it's still OK to accept the change if it is genuinely an improvement).
|
||||
- Encourage authors who are making whitespace fixes to do
|
||||
so in the first commit of their PR, and then add other changes on top of that. This
|
||||
makes both merges and reviews easier. Watch out especially for a trivial change that
|
||||
happens in a single commit along with a large amount of whitespace cleanup
|
||||
(and if you see that, encourage the author to fix it).
|
||||
(it's still OK to accept the change if it is genuinely an improvement).
|
||||
|
||||
Encourage authors who are making whitespace fixes to do
|
||||
so in the first commit of their PR, and then add other changes on top of that. This
|
||||
makes both merges and reviews easier. Watch out especially for a trivial change that
|
||||
happens in a single commit along with a large amount of whitespace cleanup
|
||||
(and if you see that, encourage the author to fix it).
|
||||
|
||||
As a reviewer, if you identify small issues with a PR that aren't essential to the meaning,
|
||||
such as typos or incorrect whitespace, prefix your comments with `nit:`.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
title: Suggesting content improvements
|
||||
content_type: concept
|
||||
weight: 10
|
||||
weight: 20
|
||||
card:
|
||||
name: contribute
|
||||
weight: 15
|
||||
|
|
|
|||
|
|
@ -149,6 +149,10 @@
|
|||
/docs/contribute/intermediate/ /docs/contribute/ 301
|
||||
/docs/contribute/new-content/overview/ /docs/contribute/new-content/ 301
|
||||
|
||||
# Previous page is now /docs/contribute/blog/ and /docs/contribute/new-content/case-studies
|
||||
# No direct redirect is correct to make
|
||||
/docs/contribute/new-content/blogs-case-studies/ /docs/contribute/new-content/ 302
|
||||
|
||||
/docs/deprecate/ /docs/reference/using-api/deprecation-policy/ 301
|
||||
/docs/deprecated/ /docs/reference/using-api/deprecation-policy/ 301
|
||||
/docs/deprecation-policy/ /docs/reference/using-api/deprecation-policy/ 301
|
||||
|
|
|
|||
Loading…
Reference in New Issue