From 427ccfbc7d423d8763ed756f3b8c888b7de3cf34 Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Thu, 18 Jun 2020 22:00:10 -0400 Subject: [PATCH] Add frontmatter descriptions to the contributor guide docs --- contributors/guide/README.md | 11 ----------- contributors/guide/coding-conventions.md | 4 +++- contributors/guide/contributing.md | 3 ++- contributors/guide/contributor-cheatsheet/README.md | 10 ++++++++++ contributors/guide/expectations.md | 4 +++- contributors/guide/first-contribution.md | 4 +++- contributors/guide/getting-started.md | 6 +++++- contributors/guide/github-workflow.md | 5 ++++- contributors/guide/help-wanted.md | 5 ++++- contributors/guide/issue-triage.md | 5 ++++- contributors/guide/non-code-contributions.md | 6 +++++- contributors/guide/owners.md | 5 ++++- contributors/guide/pull-requests.md | 6 +++++- contributors/guide/release-notes.md | 4 +++- contributors/guide/review-guidelines.md | 4 +++- contributors/guide/scalability-good-practices.md | 5 ----- contributors/guide/style-guide.md | 3 ++- 17 files changed, 60 insertions(+), 30 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index c7869e0240c..6b1e834f428 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -1,14 +1,3 @@ ---- -title: "Contributors Guide" -weight: 1 -slug: "guide" ---- - - - This document is the single source of truth for how to contribute to the code base. Feel free to browse the [open issues](https://github.com/kubernetes/community/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%2Fcontributor-guide) and file new ones, all feedback welcome! diff --git a/contributors/guide/coding-conventions.md b/contributors/guide/coding-conventions.md index 44fbba49d48..33483a96127 100644 --- a/contributors/guide/coding-conventions.md +++ b/contributors/guide/coding-conventions.md @@ -1,7 +1,9 @@ --- title: "Coding Conventions" weight: 8 -slug: "coding-conventions" +description: | + A collection of guidelines, style suggestions, and tips for writing code in + the different programming languages used throughout the project. --- **Table of Contents** diff --git a/contributors/guide/contributing.md b/contributors/guide/contributing.md index 1b3e0fc540b..208e3785304 100644 --- a/contributors/guide/contributing.md +++ b/contributors/guide/contributing.md @@ -1,7 +1,8 @@ --- title: "Contributing to Kubernetes" weight: 4 -slug: "contributing" +description: | + An entrypoint to getting started with contributing to the Kubernetes project. --- # Contributing diff --git a/contributors/guide/contributor-cheatsheet/README.md b/contributors/guide/contributor-cheatsheet/README.md index d20d574b488..f6e9632dc06 100644 --- a/contributors/guide/contributor-cheatsheet/README.md +++ b/contributors/guide/contributor-cheatsheet/README.md @@ -1,3 +1,13 @@ +--- +title: Contributor Cheatsheet +weight: 2 +description: | + A list of common resources when contributing to Kubernetes, tips, tricks, and + common best practices used within the Kubernetes project. It is a "TL;DR" or + quick reference of useful information to make your GitHub contribution experience + better. +--- + # Kubernetes Contributor Cheat Sheet diff --git a/contributors/guide/expectations.md b/contributors/guide/expectations.md index a726718266e..7548fcbf736 100644 --- a/contributors/guide/expectations.md +++ b/contributors/guide/expectations.md @@ -1,7 +1,9 @@ --- title: "Community Expectations" weight: 17 -slug: "expectations" +description: | + Expectations of conduct and code review that govern all members of the + community. --- Kubernetes is a community project. Consequently, it is wholly dependent on diff --git a/contributors/guide/first-contribution.md b/contributors/guide/first-contribution.md index 326a2570c71..4d3388d815b 100644 --- a/contributors/guide/first-contribution.md +++ b/contributors/guide/first-contribution.md @@ -1,7 +1,9 @@ --- title: "Making your First Contribution" weight: 3 -slug: "first-contribution" +description: | + Not sure where to make your first contribution? This doc has some tips and + ideas to help get you started. --- # Your First Contribution diff --git a/contributors/guide/getting-started.md b/contributors/guide/getting-started.md index 850fc0ce29f..339e6d443ad 100644 --- a/contributors/guide/getting-started.md +++ b/contributors/guide/getting-started.md @@ -1,7 +1,11 @@ --- title: "Getting Started" weight: 2 -slug: "getting-started" +description: | + A small list of things that you should read and be familiar with before you + get started with contributing. This includes such things as signing the + Contributor License Agreement, familiarizing yourself with our Code of Conduct + and more. --- # Before you get started diff --git a/contributors/guide/github-workflow.md b/contributors/guide/github-workflow.md index aae63e632e4..f88c45c9638 100644 --- a/contributors/guide/github-workflow.md +++ b/contributors/guide/github-workflow.md @@ -1,7 +1,10 @@ --- title: "GitHub Workflow" weight: 6 -slug: "github-workflow" +description: | + An overview of the GitHub workflow used by the Kubernetes project. It includes + some tips and suggestions on things such as keeping your local environment in + sync with upstream and commit hygiene. --- ![Git workflow](git_workflow.png) diff --git a/contributors/guide/help-wanted.md b/contributors/guide/help-wanted.md index b04d52ecdfe..ba0b4859f9e 100644 --- a/contributors/guide/help-wanted.md +++ b/contributors/guide/help-wanted.md @@ -1,7 +1,10 @@ --- title: "Help Wanted and Good First Issue Labels" weight: 9 -slug: "help-wanted" +description: | + Provides guidance on how and when to use the help wanted and good first issue + labels. These are used to identify issues that have been specially groomed for + new contributors. --- # Overview diff --git a/contributors/guide/issue-triage.md b/contributors/guide/issue-triage.md index e474e92cbc6..43f2e046a2c 100644 --- a/contributors/guide/issue-triage.md +++ b/contributors/guide/issue-triage.md @@ -1,7 +1,10 @@ --- title: "Issue Triage Guidelines" weight: 10 -slug: "issue-triage" +description: | + These guidelines serve as a primary document for triaging incoming issues to + Kubernetes. SIGs and projects are encouraged to use this guidance as a + starting point, and customize to address specific triaging needs. --- # Issue Triage: A Primer diff --git a/contributors/guide/non-code-contributions.md b/contributors/guide/non-code-contributions.md index c74fdf8fe9c..c76b118c341 100644 --- a/contributors/guide/non-code-contributions.md +++ b/contributors/guide/non-code-contributions.md @@ -1,7 +1,11 @@ --- title: "Non-code Contributions" weight: 11 -slug: "non-code-contributions" +description: | + Looking for a good entrance into the project? or to do something different? + There are many ways to contribute to the the Kubernetes project without having + to have coding experience: issue triage, writing documentation, joining the + release team and much more. --- *This section is new and in progress. Expect this document to change often.* diff --git a/contributors/guide/owners.md b/contributors/guide/owners.md index 21037255415..ffbe22d2d7a 100644 --- a/contributors/guide/owners.md +++ b/contributors/guide/owners.md @@ -1,7 +1,10 @@ --- title: "OWNERS Files" weight: 15 -slug: "owners" +description: | + OWNERS files are used to designate responsibility over different parts of the + Kubernetes codebase and serve as the implementation mechanism for the two-phase + code review process used by the project. --- ## Overview diff --git a/contributors/guide/pull-requests.md b/contributors/guide/pull-requests.md index 6a267a58811..083b8c1ac2a 100644 --- a/contributors/guide/pull-requests.md +++ b/contributors/guide/pull-requests.md @@ -1,7 +1,11 @@ --- title: "Pull Request Process" weight: 5 -slug: "pull-requests" +description: | + Explains the process and best practices for submitting a pull request + to the Kubernetes project and its associated sub-repositories. It should serve + as a reference for all contributors, and be useful especially to new or + infrequent submitters. --- This doc explains the process and best practices for submitting a pull request to the [Kubernetes project](https://github.com/kubernetes/kubernetes) and its associated sub-repositories. It should serve as a reference for all contributors, and be useful especially to new and infrequent submitters. diff --git a/contributors/guide/release-notes.md b/contributors/guide/release-notes.md index 404b8d047fe..a5079ffdb28 100644 --- a/contributors/guide/release-notes.md +++ b/contributors/guide/release-notes.md @@ -1,7 +1,9 @@ --- title: "Adding Release Notes" weight: 12 -slug: "release-notes" +description: | + Guidance on providing release notes for changes made to the main Kubernetes + project repo. --- On the kubernetes/kubernetes repository, release notes are required for any pull diff --git a/contributors/guide/review-guidelines.md b/contributors/guide/review-guidelines.md index 4526e1779ce..98fab4deb4f 100644 --- a/contributors/guide/review-guidelines.md +++ b/contributors/guide/review-guidelines.md @@ -1,7 +1,9 @@ --- title: "Pull Request Review Guidelines" weight: 13 -slug: "review-guidelines" +description: | + A collection of of tips to help both those looking to get their PR reviewed + and the code reviewers themselves. --- - [Tips for getting your PR reviewed](#tips-for-getting-your-pr-reviewed) - [Use Tokens to signal the state of your PR](#use-tokens-to-signal-the-state-of-your-pr) diff --git a/contributors/guide/scalability-good-practices.md b/contributors/guide/scalability-good-practices.md index c547c445a7f..de9639c3248 100644 --- a/contributors/guide/scalability-good-practices.md +++ b/contributors/guide/scalability-good-practices.md @@ -1,8 +1,3 @@ ---- -title: "Scalability Good Practices" -weight: 13 -slug: "scalability-good-practices" ---- *This document is written for contributors who would like to avoid their code being reverted for performance reasons* diff --git a/contributors/guide/style-guide.md b/contributors/guide/style-guide.md index eaefbcccec9..ef5615ab32d 100644 --- a/contributors/guide/style-guide.md +++ b/contributors/guide/style-guide.md @@ -1,7 +1,8 @@ --- title: "Documentation Style Guide" weight: 14 -slug: "style-guide" +description: | + A comprehensive collection of guidelines for writing contributor documentation. --- This style guide is for content in the Kubernetes github [community repository].