Reorganize docs contrib guide#9510
Reorganize docs contrib guide#9510k8s-ci-robot merged 9 commits intokubernetes:masterfrom mdlinville:contribute-to-docs-reorg
Conversation
|
Deploy preview for kubernetes-io-master-staging ready! Built with commit ae0c7a0 https://deploy-preview-9510--kubernetes-io-master-staging.netlify.com |
|
/hold cancel |
|
/assign @tallt0m |
|
@MistyHacks: GitHub didn't allow me to assign the following users: tallt0m. Note that only kubernetes members and repo collaborators can be assigned. DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
| use multiples of 10, to account for adding topics later. For instance, a topic | ||
| with weight `10` will come before one with weight `20`. | ||
|
|
||
| ## Including code from another file |
There was a problem hiding this comment.
I have a PR under review for this sub-topic. #9574
There was a problem hiding this comment.
@tengqm Can you let me know when your PR is merged so I can make sure those changes get into this branch? I'm sure your PR will be ready before mine has been completely reviewed.
There was a problem hiding this comment.
I just merged it. Let me now rebase this PR and integrate that content into the new location.
| @@ -1,4 +1,5 @@ | |||
| <!-- Thanks for filing an issue! Before submitting, please fill in the following information. --> | |||
| <!-- See https://kubernetes.io/docs/contribute/start/ for guidance on writing an actionable issue description. --> | |||
There was a problem hiding this comment.
Nice! Very cool to have a helpful pointer here.
| @@ -1,6 +1,7 @@ | |||
| >^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |||
| > Please delete this note before submitting the pull request. | |||
| > For 1.12 Features: set Milestone to 1.12 and Base Branch to release-1.12 | |||
There was a problem hiding this comment.
Do we have instructions somewhere that provides an example on how to set the base branch to release-1.12? For folks new to git that would be very helpful. Also do we have instructions somewhere on setting the milestone. People will ask how to do that as well
There was a problem hiding this comment.
.github/PULL_REQUEST_TEMPLATE.md
Outdated
| >^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| > Please delete this note before submitting the pull request. | ||
| > For 1.12 Features: set Milestone to 1.12 and Base Branch to release-1.12 | ||
| > For help editing and submitting pull requests, see https://kubernetes.io/contribute/start/ |
| and whether you self-identify as a developer, an end user, or someone who just | ||
| can't stand seeing typos. | ||
|
|
||
| Looking for the [style guide](/docs/contribute/style/style-guide/)? |
There was a problem hiding this comment.
Instead of "Looking for the" Perhaps say, Before you start contributing we highly recommend you review our [style guide] . This will help to get your pull requests merged more quickly.
There was a problem hiding this comment.
That's convered in https://deploy-preview-9510--kubernetes-io-master-staging.netlify.com/docs/contribute/start/#style-guidelines. The one here is just for people who expected to find the style guide right at the top of the contribute/ level, as a convenience.
| - Participate in a Kubernetes release team as a docs representative | ||
| - Propose improvements to the style guide | ||
| - Propose improvements to docs tests | ||
| - Propose improvements to the Kubernetes website or other tooling |
There was a problem hiding this comment.
Should Approve and Merge PRs be on this list?
| currently work and why past decisions have been made before proposing sweeping | ||
| changes. The quickest way to get answers to questions about how the documentation | ||
| currently works is to ask in the #sig-docs Slack channel on | ||
| [kubernetes.slack.com](https://kubernetes.slack.com) |
|
|
||
| ### Approvers | ||
|
|
||
| Approvers have the ability to merge a PR. |
There was a problem hiding this comment.
I thought this was called maintainer
|
|
||
| {{% capture overview %}} | ||
|
|
||
| When contributing new topics, apply one of the following templates to them. |
There was a problem hiding this comment.
So awesome to have this documented!!!!
| | discussion | no | | ||
| | whatsnext | no | | ||
|
|
||
| The page's body will look like this (without any optional sections you don't |
There was a problem hiding this comment.
So are any of the sections below optional or are they mandatory? Its unclear to me
There was a problem hiding this comment.
I don't understand. The "Required" column in the table should cover this, I thought.
| - For `overview`, use a paragraph to set context for the entire topic. | ||
| - Add the `{{< toc >}}` shortcode to show an in-page table of contents. | ||
| - For `prerequisites`, use bullet lists when possible. Add additional | ||
| prerequisites below the ones included by default. |
There was a problem hiding this comment.
Is is the < include "task-tutorial-prereqs.md> that are the default pre-requisites? This should be clarified
There was a problem hiding this comment.
I added some clarification.
| `/content/en/docs/tutorials` directory, with the following characteristics: | ||
|
|
||
| - In the page's YAML front-matter, set `content_template: templates/tutorial`. | ||
| - In the page's body, set the following `capture` variables: |
There was a problem hiding this comment.
Perhaps provide an example on how to set one of these variables
There was a problem hiding this comment.
I think the inline examples show it pretty well, right?
content/en/docs/contribute/start.md
Outdated
| ## Write a blog post | ||
|
|
||
| Anyone can write a blog post and submit it for review. Blog posts should not be | ||
| commercial in nature and should consiste of content that will apply broadly to |
|
|
||
| {{% capture prerequisites %}} | ||
|
|
||
| {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} |
There was a problem hiding this comment.
Why is this basic version check necessary for every task/tutorial? I could understand using a version check if the instructions in the task pertain to a specific version, otherwise, it seems odd to remind the user to check their version without saying why.
There was a problem hiding this comment.
This was decided by the SIG when the templates were decided upon. Not my new change. :)
|
From Slack with @MistyHacks:
Here's a summary of the operative criteria. Hopefully I got everything--other maintainers, please chime in!
|
content/en/docs/contribute/start.md
Outdated
|
|
||
| When you are comfortable with all of the tasks discussed in this topic and you | ||
| want to engage with the Kubernetes docs team in deeper ways, read the | ||
| [internediate docs contribution guide](/docs/contribute/intermediate/). |
There was a problem hiding this comment.
spelling nit: internediate
content/en/docs/contribute/start.md
Outdated
| docs. | ||
|
|
||
| 2. By default, the only filter that is applied is `open`, so you don't see | ||
| pull reuests that have already been closed or merged. It's a good idea to |
All of this feedback was addressed.
|
Troubleshooting netlify failure. |
|
Netlify build looks good:
|
It was being interpreted as a Hugo shortcode.
|
Confirmed the last commit fixed the bug that was breaking Netlify and also adds a related test to the smoke tests page. This is ready to go. 🍾 |
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: chenopis The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Preview at https://deploy-preview-9510--kubernetes-io-master-staging.netlify.com/docs/contribute/
This is a HUGE PR to review. I'm very sorry about that. It does the following major things:
/docs/contribute/There are still some whitespace errors (trailing, mostly) that I need to find and fix. But this is ready to review.