diff options
| -rw-r--r-- | contributors/guide/README.md | 64 | ||||
| -rw-r--r-- | contributors/guide/bug-bounty.md | 2 | ||||
| -rw-r--r-- | contributors/guide/github-workflow.md | 47 | ||||
| -rw-r--r-- | contributors/guide/non-code-contributions.md | 2 | ||||
| -rw-r--r-- | contributors/guide/pull-requests.md | 43 | ||||
| -rw-r--r-- | contributors/guide/release-notes.md | 2 | ||||
| -rw-r--r-- | contributors/guide/style-guide.md | 54 |
7 files changed, 124 insertions, 90 deletions
diff --git a/contributors/guide/README.md b/contributors/guide/README.md index d6040224..e95d3704 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -4,7 +4,6 @@ weight: 1 slug: "guide" --- - <!-- Contributing to this document? Please use semantic line feeds for readability: http://rhodesmill.org/brandon/2012/one-sentence-per-line/ @@ -17,35 +16,38 @@ Feel free to browse the [open issues](https://github.com/kubernetes/community/is Welcome to Kubernetes! -- [Before you get started](#before-you-get-started) - - [Sign the CLA](#sign-the-cla) - - [Code of Conduct](#code-of-conduct) - - [Setting up your development - environment](#setting-up-your-development-environment) - - [Community Expectations and Roles](#community-expectations-and-roles) - - [Thanks](#thanks) -- [Your First Contribution](#your-first-contribution) - - [Find something to work on](#find-something-to-work-on) - - [Find a good first topic](#find-a-good-first-topic) - - [Learn about SIGs](#learn-about-sigs) - - [SIG-specific contributing guidelines](#sig-specific-contributing-guidelines) - - [File an Issue](#file-an-issue) -- [Contributing](#contributing) - - [Communication](#communication) - - [GitHub workflow](#github-workflow) - - [Open a Pull Request](#open-a-pull-request) - - [Code Review](#code-review) - - [Testing](#testing) - - [Security](#security) - - [Documentation](#documentation) - - [Issues Management or Triage](#issues-management-or-triage) -- [Kubernetes Contributor Playground](#kubernetes-contributor-playground) - - [Youtube playlist](#youtube-playlist) -- [Community](#community) - - [Communication](#communication-1) - - [Events](#events) - - [Meetups](#meetups) - - [Mentorship](#mentorship) +- [Welcome](#welcome) +- [Before you get started](#before-you-get-started) + - [Sign the CLA](#sign-the-cla) + - [Code of Conduct](#code-of-conduct) + - [Setting up your development environment](#setting-up-your-development-environment) + - [Community Expectations and Roles](#community-expectations-and-roles) +- [Your First Contribution](#your-first-contribution) + - [Find something to work on](#find-something-to-work-on) + - [Find a good first topic](#find-a-good-first-topic) + - [Issue Assignment in Github](#issue-assignment-in-github) + - [Learn about SIGs](#learn-about-sigs) + - [SIG structure](#sig-structure) + - [Find a SIG that is related to your contribution](#find-a-sig-that-is-related-to-your-contribution) + - [SIG-specific contributing guidelines](#sig-specific-contributing-guidelines) + - [File an Issue](#file-an-issue) +- [Contributing](#contributing) + - [Communication](#communication) + - [GitHub workflow](#github-workflow) + - [Open a Pull Request](#open-a-pull-request) + - [Code Review](#code-review) + - [Testing](#testing) + - [Security](#security) + - [Documentation](#documentation) + - [Issues Management or Triage](#issues-management-or-triage) +- [Kubernetes Contributor Playground](#kubernetes-contributor-playground) + - [Youtube playlist](#youtube-playlist) +- [Community](#community) + - [Communication](#communication-1) + - [Events](#events) + - [Meetups](#meetups) + - [Mentorship](#mentorship) +- [Advanced Topics](#advanced-topics) # Before you get started @@ -146,8 +148,8 @@ If you are not sure about the correct SIG for an issue, you can try SIG-contribu ### SIG-specific contributing guidelines Some SIGs have their own `CONTRIBUTING.md` files, which may contain extra information or guidelines in addition to these general ones. These are located in the SIG-specific community directories: + - [`/sig-apps/CONTRIBUTING.md`](/sig-apps/CONTRIBUTING.md) -- [`/sig-aws/CONTRIBUTING.md`](/sig-aws/CONTRIBUTING.md) - [`/sig-cli/CONTRIBUTING.md`](/sig-cli/CONTRIBUTING.md) - [`/sig-multicluster/CONTRIBUTING.md`](/sig-multicluster/CONTRIBUTING.md) - [`/sig-storage/CONTRIBUTING.md`](/sig-storage/CONTRIBUTING.md) diff --git a/contributors/guide/bug-bounty.md b/contributors/guide/bug-bounty.md index 32b72819..60f48b43 100644 --- a/contributors/guide/bug-bounty.md +++ b/contributors/guide/bug-bounty.md @@ -1,7 +1,7 @@ --- title: "Bug Bounty Programs" weight: 1 -slug: "bounties" +slug: "bug-bounty" --- This program is a **work in progress**. This tracks the currently proposed program, but the bug diff --git a/contributors/guide/github-workflow.md b/contributors/guide/github-workflow.md index 8174aaf8..1963b206 100644 --- a/contributors/guide/github-workflow.md +++ b/contributors/guide/github-workflow.md @@ -1,7 +1,7 @@ --- title: "GitHub Workflow" weight: 1 -slug: "github" +slug: "github-workflow" ---  @@ -173,38 +173,35 @@ _If you have upstream write access_, please refrain from using the `Revert` button in the GitHub UI for creating the PR, because GitHub will create the PR branch inside the main repository rather than inside your fork. -1. Create a branch and sync it with upstream. +- Create a branch and sync it with upstream. -```sh -# create a branch -git checkout -b myrevert - -# sync the branch with upstream -git fetch upstream -git rebase upstream/master -``` + ```sh + # create a branch + git checkout -b myrevert -2. If the commit you wish to revert is a: + # sync the branch with upstream + git fetch upstream + git rebase upstream/master + ``` +- If the commit you wish to revert is a:<br> + - **merge commit:** -- merge commit: + ```sh + # SHA is the hash of the merge commit you wish to revert + git revert -m 1 SHA + ``` -```sh -# SHA is the hash of the merge commit you wish to revert -git revert -m 1 SHA -``` - -- single commit: + - **single commit:** -```sh -# SHA is the hash of the single commit you wish to revert -git revert SHA -``` + ```sh + # SHA is the hash of the single commit you wish to revert + git revert SHA + ``` -3. This will create a new commit reverting the changes. -Push this new commit to your remote. +- This will create a new commit reverting the changes. Push this new commit to your remote. ```sh git push ${your_remote_name} myrevert ``` -4. [Create a Pull Request](#7-create-a-pull-request) using this branch. +- [Create a Pull Request](#7-create-a-pull-request) using this branch.
\ No newline at end of file diff --git a/contributors/guide/non-code-contributions.md b/contributors/guide/non-code-contributions.md index 43fd10e2..4ec2838c 100644 --- a/contributors/guide/non-code-contributions.md +++ b/contributors/guide/non-code-contributions.md @@ -1,7 +1,7 @@ --- title: "Non-code Contributions" weight: 1 -slug: "non-code" +slug: "non-code-contributions" --- *This section is new and in progress. Expect this document to change often.* diff --git a/contributors/guide/pull-requests.md b/contributors/guide/pull-requests.md index d2e252c8..c403c974 100644 --- a/contributors/guide/pull-requests.md +++ b/contributors/guide/pull-requests.md @@ -7,27 +7,28 @@ slug: "pull-requests" 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. - [Before You Submit a Pull Request](#before-you-submit-a-pull-request) - * [Run Local Verifications](#run-local-verifications) + - [Run Local Verifications](#run-local-verifications) - [The Pull Request Submit Process](#the-pull-request-submit-process) - * [The Testing and Merge Workflow](#the-testing-and-merge-workflow) - * [Marking Unfinished Pull Requests](#marking-unfinished-pull-requests) - * [Comment Commands Reference](#comment-commands-reference) - * [Automation](#automation) - * [How the e2e Tests Work](#how-the-e2e-tests-work) -- [Why was my Pull Request closed?](#why-was-my-pull-request-closed) -- [Why is my Pull Request not getting reviewed?](#why-is-my-pull-request-not-getting-reviewed) + - [The Testing and Merge Workflow](#the-testing-and-merge-workflow) + - [Marking Unfinished Pull Requests](#marking-unfinished-pull-requests) + - [Pull Requests and the Release Cycle](#pull-requests-and-the-release-cycle) + - [Comment Commands Reference](#comment-commands-reference) + - [Automation](#automation) + - [How the e2e Tests Work](#how-the-e2e-tests-work) +- [Why was my pull request closed?](#why-was-my-pull-request-closed) +- [Why is my pull request not getting reviewed?](#why-is-my-pull-request-not-getting-reviewed) - [Best Practices for Faster Reviews](#best-practices-for-faster-reviews) - * [0. Familiarize yourself with project conventions](#0-familiarize-yourself-with-project-conventions) - * [1. Is the feature wanted? File a Kubernetes Enhancement Proposal](#1-is-the-feature-wanted-file-a-kubernetes-enhancement-proposal) - * [2. Smaller Is Better: Small Commits, Small Pull Requests](#2-smaller-is-better-small-commits-small-pull-requests) - * [3. Open a Different Pull Request for Fixes and Generic Features](#3-open-a-different-pull-request-for-fixes-and-generic-features) - * [4. Comments Matter](#4-comments-matter) - * [5. Test](#5-test) - * [6. Squashing and Commit Titles](#6-squashing-and-commit-titles) - * [7. KISS, YAGNI, MVP, etc.](#7-kiss-yagni-mvp-etc) - * [8. It's OK to Push Back](#8-its-ok-to-push-back) - * [9. Common Sense and Courtesy](#9-common-sense-and-courtesy) - * [10. Trivial Edits](#10-trivial-edits) + - [0. Familiarize yourself with project conventions](#0-familiarize-yourself-with-project-conventions) + - [1. Is the feature wanted? File a Kubernetes Enhancement Proposal](#1-is-the-feature-wanted-file-a-kubernetes-enhancement-proposal) + - [2. Smaller Is Better: Small Commits, Small Pull Requests](#2-smaller-is-better-small-commits-small-pull-requests) + - [3. Open a Different Pull Request for Fixes and Generic Features](#3-open-a-different-pull-request-for-fixes-and-generic-features) + - [4. Comments Matter](#4-comments-matter) + - [5. Test](#5-test) + - [6. Squashing and Commit Titles](#6-squashing-and-commit-titles) + - [7. KISS, YAGNI, MVP, etc.](#7-kiss-yagni-mvp-etc) + - [8. It's OK to Push Back](#8-its-ok-to-push-back) + - [9. Common Sense and Courtesy](#9-common-sense-and-courtesy) + - [10. Trivial Edits](#10-trivial-edits) # Before You Submit a Pull Request @@ -62,7 +63,7 @@ The Kubernetes merge workflow uses labels, applied by [commands](https://prow.k8 _Example:_ To apply a SIG label, you would type in a comment: ``` -/sig aws +/sig apps ``` *NOTE: For pull requests that are in progress but not ready for review, @@ -228,7 +229,7 @@ We want every pull request to be useful on its own, so use your best judgment on As a rule of thumb, if your pull request is directly related to Feature-X and nothing else, it should probably be part of the Feature-X pull request. If you can explain why you are doing seemingly no-op work ("it makes the Feature-X change easier, I promise") we'll probably be OK with it. If you can imagine someone finding value independently of Feature-X, try it as a pull request. (Do not link pull requests by `#` in a commit description, because GitHub creates lots of spam. Instead, reference other pull requests via the pull request your commit is in.) -## 3. Open a Different pull request for Fixes and Generic Features +## 3. Open a Different Pull Request for Fixes and Generic Features **Put changes that are unrelated to your feature into a different pull request.** diff --git a/contributors/guide/release-notes.md b/contributors/guide/release-notes.md index 0b3223c4..1c217cd6 100644 --- a/contributors/guide/release-notes.md +++ b/contributors/guide/release-notes.md @@ -1,7 +1,7 @@ --- title: "Adding Release Notes" weight: 1 -slug: "adding-release-notes" +slug: "release-notes" --- On the kubernetes/kubernetes repository, release notes are required for any pull request with user-visible changes, such as bug-fixes, feature additions, and output format changes. diff --git a/contributors/guide/style-guide.md b/contributors/guide/style-guide.md index 38acb36c..3b81ef5b 100644 --- a/contributors/guide/style-guide.md +++ b/contributors/guide/style-guide.md @@ -1,7 +1,7 @@ --- title: "Documentation Style Guide" weight: 1 -slug: "documentation-style-guide" +slug: "style-guide" --- This style guide is for content in the Kubernetes github [community repository]. @@ -10,21 +10,23 @@ It is an extension of the [Kubernetes documentation style-guide]. These are **guidelines**, not rules. Use your best judgement. - [Cheatsheet](#cheatsheet) -- [Content design, formatting, and language](#content-formatting-and-language) - - [Contact information](#contact-information) - - [Dates and times](#dates-and-times) - - [Diagrams, images and other assets](#diagrams-images-and-other-assets) + - [Cheatsheet: Content Design, Formatting, and Language](#cheatsheet-content-design-formatting-and-language) + - [Cheatsheet: Markdown](#cheatsheet-markdown) +- [Content Design, Formatting, and Language](#content-design-formatting-and-language) + - [Contact Information](#contact-information) + - [Dates and Times](#dates-and-times) + - [Diagrams, Images and Other Assets](#diagrams-images-and-other-assets) - [Document Layout](#document-layout) - - [Formatting text](#formatting-text) - - [Language, grammar, and tone](#language-grammar-and-tone) - - [Moving a document](#moving-a-document) + - [Formatting Text](#formatting-text) + - [Language, Grammar and Tone](#language-grammar-and-tone) + - [Moving a Document](#moving-a-document) - [Punctuation](#punctuation) - [Quotation](#quotation) -- [Markdown formatting](#markdown-and-formatting) +- [Markdown Formatting](#markdown-formatting) - [Code Blocks](#code-blocks) - [Emphasis](#emphasis) - [Headings](#headings) - - [Horizontal Lines](#horizontal-lines) + - [Horizontal Rules](#horizontal-rules) - [Line Length](#line-length) - [Links](#links) - [Lists](#lists) @@ -38,9 +40,11 @@ These are **guidelines**, not rules. Use your best judgement. ### Cheatsheet: Content Design, Formatting, and Language **[Contact Information:](#contact-information)** + - Use official Kubernetes contact information. **[Dates and Times:](#dates-and-times)** + - Format dates as `month day, year`. (December 13, 2018) - When conveying a date in numerical form, use [ISO 8601] Format: `yyyy-mm-dd`. - Use the 24 hour clock when referencing time. @@ -53,6 +57,7 @@ These are **guidelines**, not rules. Use your best judgement. - `http://www.thetimezoneconverter.com/?t=<TIME REFERENCE>&tz=<TZ REFERENCE>` **[Diagrams, Images and Other Assets:](#diagrams-images-and-other-assets)** + - Images and other assets should be stored in the same directory as the document that is referencing it. - Filenames should be lowercase and descriptive of what they are referencing. @@ -61,6 +66,7 @@ These are **guidelines**, not rules. Use your best judgement. - Use the [Kubernetes icon set] for architectural diagrams. **[Document Layout:](#document-layout)** + - Documents should follow the general template of: - Document metadata (if appropriate). - Title in `H1` (a single `#`). @@ -71,6 +77,7 @@ These are **guidelines**, not rules. Use your best judgement. - Large content or topic shifts should be separated with a horizontal rule. **[Formatting Text:](#formatting-text)** + - API objects: - Follow the established [API naming convention] when referring to API Objects. - Do not split API object names into their components. @@ -84,6 +91,7 @@ These are **guidelines**, not rules. Use your best judgement. - Object field names. **[Language, Grammar and Tone:](#language)** + - Documentation should be written in English. - Prefer an active voice and present tense when possible. - Use simple and direct language. @@ -97,12 +105,14 @@ These are **guidelines**, not rules. Use your best judgement. document unless it is commonly known. (example: TCP/IP) **[Moving a Document:](#moving-a-document)** + - Use `[git-mv]` to move documents. - Commit moved documents separately from any other changes. - When a document has moved, leave a tombstone file with a removal date in its place. **[Punctuation:](#punctuation)** + - Do not use punctuation in headings. - End full sentences with a period. - **Exception:** When a sentence ends with a URL or if the text would be @@ -123,6 +133,7 @@ These are **guidelines**, not rules. Use your best judgement. ### Cheatsheet: Markdown **[Code Blocks:](#code-blocks)** + - When possible, reference the language at the beginning of a Code Block. - When a code block is used to reference a shell, do not include the command prompt (`$`). @@ -130,11 +141,13 @@ These are **guidelines**, not rules. Use your best judgement. - Separate commands from output. **[Emphasis:](#emphasis)** + - Use two asterisks (`**`) for **Bold** text. - Use an underscore (`_`) for _Italics_. - Use two tildes (`~~`) for ~~Strikethrough~~. **[Headings:](#headings)** + - Use a single `H1` (`#`) Heading per document. - **Exception:** `H1` may be used multiple times in the same document when there is a large content shift or "chapter" change. @@ -149,13 +162,16 @@ These are **guidelines**, not rules. Use your best judgement. - Avoid using links in headings. **[Horizontal Rules:](#horizontal-lines)** + - Use three dashes (`---`) to denote a horizontal rule. - Use a horizontal rule (`---`) to logically separate large sections. **[Line Length:](#line-length)** + - Prefer an 80 character line limit. **[Links:](#links)** + - Prefer using reference style links over inline style links. - When linking within the same directory, use a relative link. - When linking to a document outside of the current directory, use the absolute @@ -166,6 +182,7 @@ These are **guidelines**, not rules. Use your best judgement. - sigs.k8s.io -> github.com/kubernetes-sigs **[Lists:](#lists)** + - Capitalize the first character of each entry unless the item is explicitly case sensitive. - End each entry with a period if it is a sentence or phrase. @@ -177,11 +194,13 @@ These are **guidelines**, not rules. Use your best judgement. two times. **[Metadata:](#metadata)** + - If the document is intended to be surfaced on the Contributor Site; include a yaml metadata header at the beginning of the document. - Metadata must include the `title` attribute. **[Tables:](#tables)** + - Use tables for structured information. - Tables do not need to adhere to the suggested line length. - Avoid long inline links. @@ -387,6 +406,7 @@ external appearance. - Tombstones function as a pointer and give users a time to update their own documentation and bookmarks. Their usefulness is time-bounded and should be removed when they would logically no longer serve their purpose. + ```markdown This file has moved to https://git.k8s.io/community/contributors/guide/README.md. @@ -430,6 +450,7 @@ external appearance. highlighting. This can be enabled by supplying the name of the language after the three back-ticks (`` ``` ``) at the start of a code block. - **Good example:** + ````` ```go import ( @@ -439,6 +460,7 @@ external appearance. ``` ````` - **Bad example:** + ````` ``` import ( @@ -453,10 +475,12 @@ external appearance. command prompt. The exception to this is when a code block is being used for raw shell output such as debug logs. - **Good example:** + ``` kubectl get pods -o wide ``` - **Bad example:** + ``` $ kubectl get pods -o wide ``` @@ -464,6 +488,7 @@ external appearance. - Separating the command from the output makes both the command and output more generally readable. - **Good example:** + ``` kubectl get pods ``` @@ -472,6 +497,7 @@ external appearance. nginx 1/1 Running 0 13s 10.200.0.4 worker0 ``` - **Bad example:** + ``` kubectl get pods NAME READY STATUS RESTARTS AGE IP NODE @@ -544,12 +570,14 @@ relative links. However, how and what they're being linked to can vary widely. large or covers many topics, place the link at the end of the logical chapter or section. - **Example:** + ``` See the [Code of Conduct] for more information. [code of conduct]: https://git.k8s.io/community/code-of-conduct.md ``` - **Example:** + ``` See the [Code of Conduct][coc] for more information. @@ -561,10 +589,12 @@ relative links. However, how and what they're being linked to can vary widely. - When the file is referenced multiple times within the same document, consider using a reference link for a quicker shorthand reference. - **Example:** + ``` See the [Code of Conduct](code-of-conduct.md) for more information ``` - **Example:** + ``` See the [Code of Conduct][coc] for more information @@ -576,6 +606,7 @@ relative links. However, how and what they're being linked to can vary widely. the link to the target or destination document will remain intact and not have to be updated. - **Example:** + ``` See the [Coding Convention] doc for more information. @@ -592,6 +623,7 @@ relative links. However, how and what they're being linked to can vary widely. | https://sigs.k8s.io | https://github.com/kubernetes-sigs | - **Example:** + ``` The super cool [prow tool] resides in the test-infra repo under the kubernetes organization @@ -626,6 +658,7 @@ relative links. However, how and what they're being linked to can vary widely. site generators such as [Jekyll] and [Hugo]. - The metadata header is a yaml block between two sets of `---`. - **Example:** + ``` --- title: Super Awesome Doc @@ -640,6 +673,7 @@ relative links. However, how and what they're being linked to can vary widely. - Use tables for structured information. - **Example:** + ``` | Column 1 | Column 2 | Column 3 | |:--------------:|:--------------:|:--------------:| |