From 1e58e3f2a01d72d6c4668bb21bf63a0aea87ad7a Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Wed, 15 Nov 2017 15:28:42 -0800 Subject: [PATCH 01/10] created /guide folder, and first draft of README for it, with some streamlined tasks --- contributors/guide/README.md | 205 +++++++++++++++++++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 contributors/guide/README.md diff --git a/contributors/guide/README.md b/contributors/guide/README.md new file mode 100644 index 00000000000..f762bcb5059 --- /dev/null +++ b/contributors/guide/README.md @@ -0,0 +1,205 @@ +**OWNER:** + +SIG-ContribX + + +# WARNING +Hello! This is the starting point for our brand new contributor guide, currently underway as per [-issue#6102](https://github.com/kubernetes/website/issues/6102) and in need of help. Please be patient, or fix a section below that needs improvement, and submit a pull request! + +Many of the links below should lead to relevant documents scattered across the community repository. Often, the linked instructions need to be updated or cleaned up. + +* If you do so, please port the relevant file from its previous location to come live in the community/contributors/guide folder, and delete its previous location. + +Please find _Improvements needed_ sections below and help us out. + +For example: +_Improvements needed_ +* kubernetes/kubernetes/contributing.md -> point to this guide + +* kubernetes/community/CONTRIBUTING.md -> Needs a rewrite + +* kubernetes/community/README.md -> Needs a rewrite + +* Individual SIG contributing documents -> add a link to this guide + +* A new developer guide will be referenced of the contributor guide as an item + + * RyanJ from Red Hat is working on this + +* Generate ToC for the section below + +[[TOC]] + +[[TOC]] + +# Welcome + +Welcome to Kubernetes! This document is the single source of truth for how to contribute to the code base. Please leave comments / suggestions if you find something is missing or incorrect. + +# Before you get started + +## Sign the CLA + +Link to [https://github.com/kubernetes/community/blob/master/CLA.md](https://github.com/kubernetes/community/blob/master/CLA.md) + +## Setting up your development environment + +If you haven’t set up your environment, please find instructions here: +[https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes) + +## Community Expectations + +Kubernetes is a community project. Consequently, it is wholly dependent on its community to provide a productive, friendly and collaborative environment. + +The first and foremost goal of the Kubernetes community to develop orchestration technology that radically simplifies the process of creating reliable distributed systems. However a second, equally important goal is the creation of a community that fosters easy, agile development of such orchestration systems. + +We therefore describe the expectations for members of the Kubernetes community. This document is intended to be a living one that evolves as the community evolves via the same PR and code review process that shapes the rest of the project. It currently covers the expectations of conduct that govern all members of the community as well as the expectations around code review that govern all active contributors to Kubernetes. + +### Code of Conduct + +Please make sure to read and observe our Code of Conduct: + +[https://github.com/cncf/foundation/blob/master/code-of-conduct.md](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) + +### Code Review + +[https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review) + +TODO: edit above link to only provide code review section. + +### Thanks + +Many thanks in advance to everyone who contributes their time and effort to making Kubernetes both a successful system as well as a successful community. The strength of our software shines in the strengths of each individual community member. Thanks! + +# Your First Contribution + +(modified from [https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes)) + +Have you ever wanted to contribute to the coolest cloud technology? We will help you understand the organization of the Kubernetes project and direct you to the best places to get started. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged. + +If you have questions about the development process, feel free to jump into our [Slack Channel](http://slack.k8s.io/) or join our [mailing list](https://groups.google.com/forum/#!forum/kubernetes-dev). + +## Find something to work on + +TODO: clean up this paragraph’s flow +Help is always welcome! + +Documentation (like the text you are reading now) can always use improvement! + +To dig deeper, read a design doc, e.g. [architecture](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/architecture.md). + +There's always code that can be clarified and variables or functions that can be renamed or commented. + +There's always a need for more test coverage. + +### Find a good first topic + +There's a [semi-curated list of issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted) that should not need deep knowledge of the system. +TODO: Clarify help-wanted issues also exist on projects other than k/kubernetes, e.g. k/kubectl. + +### Find a SIG that is related to your contribution + +After finding something to contribute, you should find a SIG. + +TODO: +- this needs work, how do I find the correct SIG? Example: I have a bugfix for kubectl, I’ve found the repo, + +- [This paragraph](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about an "unprompted" PR? +- Make people aware of “extra” contributing guidelines on a SIG. + +- File issues with all the SIGs to not have duplicate things in their CONTRIBUTING.md + +- Do not overload people with the entirety of the SIG structure; it is very intimidating + +Possible text to elaborate on: + +([Pick a SIG](https://github.com/kubernetes/community/blob/master/sig-list.md), peruse its associated [cmd](https://github.com/kubernetes/kubernetes/tree/master/cmd) directory, find a main() and read code until you find something you want to fix.) + +### File an issue + +TODO: clarify there are many k/subrepos where you can file. + +Not ready to contribute code, but see something that needs work? While we encourage everyone to contribute code, we also appreciate it when someone finds a problem. For example, here is where you file an issue to kubernetes/kubernetes: [https://github.com/kubernetes/kubernetes/issues/new](https://github.com/kubernetes/kubernetes/issues/new). Please make sure to adhere to the prompted submission guidelines. + +# Contributing + +(From: + +[https://github.com/kubernetes/community/blob/38fef055486c29e0b4d2639560c628f04504de21/contributors/devel/collab.md](https://github.com/kubernetes/community/blob/38fef055486c29e0b4d2639560c628f04504de21/contributors/devel/collab.md)) + +Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully these rules make things go more smoothly. If you find that this is not the case, please complain loudly. + +### Patches welcome + +First and foremost: as a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. ( + +### Communication + +TODO: + +* link to how to contact the correct people + +* Communicating link: [https://github.com/kubernetes/community/blob/master/communication.md](https://github.com/kubernetes/community/blob/master/communication.md) + +* or perhaps link to [https://kubernetes.io/community/](https://kubernetes.io/community/) + +* add content of [Office Hours](https://github.com/kubernetes/community/blob/master/community/office-hours.md) to either of the above contents. + +## GitHub workflow + +(from [https://github.com/kubernetes/community/blob/master/contributors/devel/development.md](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md)) + +## Collaborative Development + +[https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md) + +## Open a PR + +PR workflow is described here: + +[https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow](https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow) + +## Code Review + +Our general code review ideals are outlined in our [Collaborative development outline.](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md) + +### Code Review Process + +TODO: +Include some of the explanations from here: [https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process) + +TODO: +Explain OWNERS files and process (also found in above link) + +## Testing + +TODO: +- link to testing process + +- walkthrough of where to find what in the tests + +## Security + +TODO: elaborate + +## Documentation + +TODO: elaborate + +# Community + +To find out more about our community structure, different levels of membership and code contributors, please explore here: [https://github.com/kubernetes/community/blob/master/community-membership.md](https://github.com/kubernetes/community/blob/master/community-membership.md) +We depend on new people becoming members and regular code contributors, so please come join us. + +## Events + +Kubernetes is the main focus of CloudNativeCon/KubeCon, held every spring in Europe and winter in North America. Information about these and other community events is available on the CNCF [events](https://www.cncf.io/events/) pages. + +### Meetups + +### Kubecon + +## Mentorship + +[Link and mini description for Kubernetes Pilots should go here]. + From 94a7b4cfe62dc4850c25e4ce230bf72dbfa03a71 Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Wed, 15 Nov 2017 16:07:45 -0800 Subject: [PATCH 02/10] further cleanup --- contributors/guide/README.md | 86 ++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 39 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index f762bcb5059..48ed09c972f 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -9,6 +9,7 @@ Hello! This is the starting point for our brand new contributor guide, currently Many of the links below should lead to relevant documents scattered across the community repository. Often, the linked instructions need to be updated or cleaned up. * If you do so, please port the relevant file from its previous location to come live in the community/contributors/guide folder, and delete its previous location. +* Ultimately, all contributor guide related files will live in this folder. Please find _Improvements needed_ sections below and help us out. @@ -22,12 +23,10 @@ _Improvements needed_ * Individual SIG contributing documents -> add a link to this guide -* A new developer guide will be referenced of the contributor guide as an item - - * RyanJ from Red Hat is working on this - * Generate ToC for the section below +* Double check the outline of this document is complete + [[TOC]] [[TOC]] @@ -40,12 +39,16 @@ Welcome to Kubernetes! This document is the single source of truth for how to co ## Sign the CLA -Link to [https://github.com/kubernetes/community/blob/master/CLA.md](https://github.com/kubernetes/community/blob/master/CLA.md) +Before you can contribute, you will need to sign the [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md). ## Setting up your development environment -If you haven’t set up your environment, please find instructions here: -[https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes) +If you haven’t set up your environment, please find resources [here](https://github.com/kubernetes/community/tree/master/contributors/devel). These resources are not well organized as of currently. + +_Improvements needed_ +* A new developer guide will be created and linked to in this section. + + * RyanJ from Red Hat is working on this ## Community Expectations @@ -57,15 +60,15 @@ We therefore describe the expectations for members of the Kubernetes community. ### Code of Conduct -Please make sure to read and observe our Code of Conduct: - -[https://github.com/cncf/foundation/blob/master/code-of-conduct.md](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) +Please make sure to read and observe our [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) ### Code Review -[https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review) +For a brief description of the importance of code review, please read [On Code Review](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review). -TODO: edit above link to only provide code review section. +_Improvements needed_ +* edit above link to only provide code review section. +* decide whether this is something that belongs in this section, or should be combined with code review instructions below. ### Thanks @@ -73,65 +76,70 @@ Many thanks in advance to everyone who contributes their time and effort to maki # Your First Contribution -(modified from [https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#downloading-building-and-testing-kubernetes)) +(from [here](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#introduction)) Have you ever wanted to contribute to the coolest cloud technology? We will help you understand the organization of the Kubernetes project and direct you to the best places to get started. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged. If you have questions about the development process, feel free to jump into our [Slack Channel](http://slack.k8s.io/) or join our [mailing list](https://groups.google.com/forum/#!forum/kubernetes-dev). +_Improvements needed_ +* The doc linked is being reinvented in this README. All relevant information should be ported to a logical place in this document/foler, and the original document deleted. + ## Find something to work on -TODO: clean up this paragraph’s flow -Help is always welcome! +Help is always welcome! For example, documentation (like the text you are reading now) can always use improvement. There's always code that can be clarified and variables or functions that can be renamed or commented. There's always a need for more test coverage. +You get the idea - if you ever see something you think should be fixed, you should own it. Here is how you get started. -Documentation (like the text you are reading now) can always use improvement! +### Find a good first topic -To dig deeper, read a design doc, e.g. [architecture](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/architecture.md). +Each repository in the Kubernetes organization has beginner-friendly issues that provide a good first issue. For example, [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) has [help-wanted issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted) that should not need deep knowledge of the system. +Another good strategy is to find a documentation improvement, such as a missing/broken link, which will give you exposure to the code submission/review process without the added complication of technical depth. -There's always code that can be clarified and variables or functions that can be renamed or commented. +_Improvements needed_ +* Clarify help-wanted issues also exist on projects other than k/kubernetes, e.g. k/kubectl. -There's always a need for more test coverage. +### Find a SIG that is related to your contribution -### Find a good first topic +You may have noticed that some repositories in the Kubernetes Organizaion are owned by Special Interest Groups, or SIGs. We organize the Kubernetes community into SIGs in order to improve our workflow and more easily manage what is a very large community project. +SIGs also have their own CONTRIBUTING.md files, which may contain extra information or guidelines in addition to these general ones. -There's a [semi-curated list of issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted) that should not need deep knowledge of the system. -TODO: Clarify help-wanted issues also exist on projects other than k/kubernetes, e.g. k/kubectl. +After finding something to contribute, you should find the appropriate SIG, which you will need in order to have your pull request approved for testing and merging. -### Find a SIG that is related to your contribution +Here is how (_information needed_) -After finding something to contribute, you should find a SIG. +_Improvements needed_ +* Clarify how someone would find the correct SIG, and what to do with that information. Link to those SIGs. -TODO: -- this needs work, how do I find the correct SIG? Example: I have a bugfix for kubectl, I’ve found the repo, +* [This paragraph](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about an "unprompted" PR? -- [This paragraph](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about an "unprompted" PR? -- Make people aware of “extra” contributing guidelines on a SIG. +* Make people aware of “extra” contributing guidelines on a SIG. -- File issues with all the SIGs to not have duplicate things in their CONTRIBUTING.md +* File issues with all the SIGs to not have duplicate things in their CONTRIBUTING.md. Keep it light, keep it clean, have only one source of truth. -- Do not overload people with the entirety of the SIG structure; it is very intimidating +* Do not overload people with the entirety of the SIG structure; it is very intimidating -Possible text to elaborate on: +* Possible text to elaborate on (the sig list should remain in its current place however): -([Pick a SIG](https://github.com/kubernetes/community/blob/master/sig-list.md), peruse its associated [cmd](https://github.com/kubernetes/kubernetes/tree/master/cmd) directory, find a main() and read code until you find something you want to fix.) + * ([Pick a SIG](https://github.com/kubernetes/community/blob/master/sig-list.md), peruse its associated [cmd](https://github.com/kubernetes/kubernetes/tree/master/cmd) directory, find a main() and read code until you find something you want to fix.) -### File an issue +### File an Issue -TODO: clarify there are many k/subrepos where you can file. +Not ready to contribute code, but see something that needs work? While we encourage everyone to contribute code, we also appreciate it when someone finds a problem. +Again, there are multiple repositories within the community, and each will have its own Issues. +For example, here is where you file an Issue to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/issues/new). Please make sure to adhere to the prompted submission guidelines. -Not ready to contribute code, but see something that needs work? While we encourage everyone to contribute code, we also appreciate it when someone finds a problem. For example, here is where you file an issue to kubernetes/kubernetes: [https://github.com/kubernetes/kubernetes/issues/new](https://github.com/kubernetes/kubernetes/issues/new). Please make sure to adhere to the prompted submission guidelines. +Improvements needed_ +* clarify there are many k/subrepos where you can file issues. Refer to "how to find and appropriate SIG" document to find out which. # Contributing -(From: - -[https://github.com/kubernetes/community/blob/38fef055486c29e0b4d2639560c628f04504de21/contributors/devel/collab.md](https://github.com/kubernetes/community/blob/38fef055486c29e0b4d2639560c628f04504de21/contributors/devel/collab.md)) +(From:[here](https://github.com/kubernetes/community/blob/38fef055486c29e0b4d2639560c628f04504de21/contributors/devel/collab.md)) Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully these rules make things go more smoothly. If you find that this is not the case, please complain loudly. ### Patches welcome -First and foremost: as a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. ( +Again, as a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. ### Communication From a280901642cd05c1de5d15da8d159b957462ecb1 Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Thu, 16 Nov 2017 08:38:13 -0800 Subject: [PATCH 03/10] keep on editing --- contributors/guide/README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 48ed09c972f..9a86eaf03fd 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -110,13 +110,13 @@ Here is how (_information needed_) _Improvements needed_ * Clarify how someone would find the correct SIG, and what to do with that information. Link to those SIGs. -* [This paragraph](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about an "unprompted" PR? +* [This paragraph](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about a PR not associated with an open issue? * Make people aware of “extra” contributing guidelines on a SIG. -* File issues with all the SIGs to not have duplicate things in their CONTRIBUTING.md. Keep it light, keep it clean, have only one source of truth. +* At the same time, file issues with all the SIGs to not have duplicate things in their CONTRIBUTING.md. Keep it light, keep it clean, have only one source of truth. -* Do not overload people with the entirety of the SIG structure; it is very intimidating +* Do not overload people with the entirety of the SIG structure; it is very intimidating to a newcomer * Possible text to elaborate on (the sig list should remain in its current place however): @@ -128,22 +128,26 @@ Not ready to contribute code, but see something that needs work? While we encour Again, there are multiple repositories within the community, and each will have its own Issues. For example, here is where you file an Issue to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/issues/new). Please make sure to adhere to the prompted submission guidelines. -Improvements needed_ +_Improvements needed_ * clarify there are many k/subrepos where you can file issues. Refer to "how to find and appropriate SIG" document to find out which. # Contributing -(From:[here](https://github.com/kubernetes/community/blob/38fef055486c29e0b4d2639560c628f04504de21/contributors/devel/collab.md)) +(From:[here](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md)) Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully these rules make things go more smoothly. If you find that this is not the case, please complain loudly. -### Patches welcome +As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. + +Our community guiding principles on how to create great code as a big group are found [here](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md). -Again, as a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. +_Improvements needed_ + +* the linked text is awfully similar to the section on [Code Review](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review), linked above. Consolidate, and decide on _one place_ in this document where it fits best. It might even be important enough to include at top level in this document(no links). ### Communication -TODO: +_Improvements needed_ * link to how to contact the correct people @@ -153,13 +157,15 @@ TODO: * add content of [Office Hours](https://github.com/kubernetes/community/blob/master/community/office-hours.md) to either of the above contents. + ## GitHub workflow -(from [https://github.com/kubernetes/community/blob/master/contributors/devel/development.md](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md)) +To check out code to work on, please refer to the following guide: +(from [here](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#workflow)) -## Collaborative Development +_Improvements needed_ -[https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md) +* move github workflow into its own file in this folder. ## Open a PR @@ -169,10 +175,6 @@ PR workflow is described here: ## Code Review -Our general code review ideals are outlined in our [Collaborative development outline.](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md) - -### Code Review Process - TODO: Include some of the explanations from here: [https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process) From bc379f5f9dde3b0f2a00aa90a7a4b1b89b6d1003 Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Thu, 16 Nov 2017 09:00:51 -0800 Subject: [PATCH 04/10] entire document edited --- contributors/guide/README.md | 48 +++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 9a86eaf03fd..aabed781756 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -139,7 +139,9 @@ Kubernetes is open source, but many of the people working on it do so as their d As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. -Our community guiding principles on how to create great code as a big group are found [here](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md). +Our community guiding principles on how to create great code as a big group are found [here](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md#code-reviews). + +If you haven't done so already make sure you have found the correct SIG for your contribution. This will ensure faster responses and a streamlined code review. (see above) _Improvements needed_ @@ -147,16 +149,9 @@ _Improvements needed_ ### Communication -_Improvements needed_ - -* link to how to contact the correct people - -* Communicating link: [https://github.com/kubernetes/community/blob/master/communication.md](https://github.com/kubernetes/community/blob/master/communication.md) - -* or perhaps link to [https://kubernetes.io/community/](https://kubernetes.io/community/) - -* add content of [Office Hours](https://github.com/kubernetes/community/blob/master/community/office-hours.md) to either of the above contents. +It is best to contact your SIG for issues related to the SIG's topic. Your SIG will be able to help you much more quickly than a general question would. Each SIG has a kubernetes slack channel that you can join as well. +For questions and troubleshooting, please feel free to use any of the methods of communication listed [here] (https://github.com/kubernetes/community/blob/master/communication.md). The [kubernetes website](https://kubernetes.io/community/) also lists this information. ## GitHub workflow @@ -175,31 +170,30 @@ PR workflow is described here: ## Code Review -TODO: -Include some of the explanations from here: [https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process) +_Improvements needed_ +* Clarify and streamline some of the explanations from [here:] (https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process) -TODO: -Explain OWNERS files and process (also found in above link) +* Explain OWNERS files and process (also found in above link) ## Testing -TODO: -- link to testing process - -- walkthrough of where to find what in the tests +_Improvements needed_ +* link to testing process +* walkthrough of where to find what in the tests (how to use, how to debug) ## Security -TODO: elaborate +_Improvements needed_ +* Please help write this section. ## Documentation -TODO: elaborate +_Improvements needed_ +* Please help write this section. # Community -To find out more about our community structure, different levels of membership and code contributors, please explore here: [https://github.com/kubernetes/community/blob/master/community-membership.md](https://github.com/kubernetes/community/blob/master/community-membership.md) -We depend on new people becoming members and regular code contributors, so please come join us. +If you haven't noticed by now, we have a large, lively, and friendly open-source community. We depend on new people becoming members and regular code contributors, so we would like you to come join us. To find out more about our community structure, different levels of membership and code contributors, please [explore here](https://github.com/kubernetes/community/blob/master/community-membership.md). ## Events @@ -207,9 +201,17 @@ Kubernetes is the main focus of CloudNativeCon/KubeCon, held every spring in Eur ### Meetups +__Improvements needed_ +* include link to meetups +* information on CNCF support for founding a Meetup + ### Kubecon +_Improvements needed_ +* write friendly blurb about KubeCon, and include links + ## Mentorship -[Link and mini description for Kubernetes Pilots should go here]. +_Improvements needed_ +* Link and mini description for Kubernetes Pilots should go here. From 6919ee9fc385a229dcddc0349cf6a12bc685554d Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Thu, 16 Nov 2017 09:01:17 -0800 Subject: [PATCH 05/10] entire document edited for real --- contributors/guide/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index aabed781756..423fdf4cbf6 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -164,9 +164,7 @@ _Improvements needed_ ## Open a PR -PR workflow is described here: - -[https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow](https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow) +PR workflow is described [here](https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow). ## Code Review From 6d24d0df0454befe9e8b980c2b3c2336587b523f Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Thu, 16 Nov 2017 09:37:43 -0800 Subject: [PATCH 06/10] tweaking --- contributors/guide/README.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 423fdf4cbf6..7bee41cb65b 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -9,11 +9,12 @@ Hello! This is the starting point for our brand new contributor guide, currently Many of the links below should lead to relevant documents scattered across the community repository. Often, the linked instructions need to be updated or cleaned up. * If you do so, please port the relevant file from its previous location to come live in the community/contributors/guide folder, and delete its previous location. -* Ultimately, all contributor guide related files will live in this folder. +* Ultimately, all contributor guide specific files will live in this folder. Please find _Improvements needed_ sections below and help us out. For example: + _Improvements needed_ * kubernetes/kubernetes/contributing.md -> point to this guide @@ -25,12 +26,6 @@ _Improvements needed_ * Generate ToC for the section below -* Double check the outline of this document is complete - -[[TOC]] - -[[TOC]] - # Welcome Welcome to Kubernetes! This document is the single source of truth for how to contribute to the code base. Please leave comments / suggestions if you find something is missing or incorrect. @@ -43,7 +38,7 @@ Before you can contribute, you will need to sign the [Contributor License Agreem ## Setting up your development environment -If you haven’t set up your environment, please find resources [here](https://github.com/kubernetes/community/tree/master/contributors/devel). These resources are not well organized as of currently. +If you haven’t set up your environment, please find resources [here](https://github.com/kubernetes/community/tree/master/contributors/devel). These resources are not well organized currently; please have patience as we are working on it. _Improvements needed_ * A new developer guide will be created and linked to in this section. From af68a7a0aa45b4230c0dc8d926842918b9c53c5d Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Thu, 16 Nov 2017 09:46:26 -0800 Subject: [PATCH 07/10] last tweaks --- contributors/guide/README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 7bee41cb65b..ced975a2da8 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -63,7 +63,7 @@ For a brief description of the importance of code review, please read [On Code R _Improvements needed_ * edit above link to only provide code review section. -* decide whether this is something that belongs in this section, or should be combined with code review instructions below. +* decide whether this is something that belongs in this section, or should be combined with Contributing instructions [below](https://github.com/guineveresaenger/community/tree/contributor-guide/contributors/guide#contributing). ### Thanks @@ -78,7 +78,7 @@ Have you ever wanted to contribute to the coolest cloud technology? We will help If you have questions about the development process, feel free to jump into our [Slack Channel](http://slack.k8s.io/) or join our [mailing list](https://groups.google.com/forum/#!forum/kubernetes-dev). _Improvements needed_ -* The doc linked is being reinvented in this README. All relevant information should be ported to a logical place in this document/foler, and the original document deleted. +* The doc linked [above](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#introduction) is being reinvented in this README. All relevant information should be ported to a logical place in this document/folder, and the original document deleted. ## Find something to work on @@ -146,12 +146,11 @@ _Improvements needed_ It is best to contact your SIG for issues related to the SIG's topic. Your SIG will be able to help you much more quickly than a general question would. Each SIG has a kubernetes slack channel that you can join as well. -For questions and troubleshooting, please feel free to use any of the methods of communication listed [here] (https://github.com/kubernetes/community/blob/master/communication.md). The [kubernetes website](https://kubernetes.io/community/) also lists this information. +For questions and troubleshooting, please feel free to use any of the methods of communication listed [here](https://github.com/kubernetes/community/blob/master/communication.md). The [kubernetes website](https://kubernetes.io/community/) also lists this information. ## GitHub workflow -To check out code to work on, please refer to the following guide: -(from [here](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#workflow)) +To check out code to work on, please refer to [this guide](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#workflow). _Improvements needed_ @@ -164,7 +163,7 @@ PR workflow is described [here](https://github.com/kubernetes/community/blob/mas ## Code Review _Improvements needed_ -* Clarify and streamline some of the explanations from [here:] (https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process) +* Clarify and streamline some of the explanations from [here](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process). * Explain OWNERS files and process (also found in above link) @@ -188,6 +187,10 @@ _Improvements needed_ If you haven't noticed by now, we have a large, lively, and friendly open-source community. We depend on new people becoming members and regular code contributors, so we would like you to come join us. To find out more about our community structure, different levels of membership and code contributors, please [explore here](https://github.com/kubernetes/community/blob/master/community-membership.md). +_Improvements needed_ + +* The top level k/community/README.md should be a good starting point for what the community is and does. (see above instructions on rewriting this file) + ## Events Kubernetes is the main focus of CloudNativeCon/KubeCon, held every spring in Europe and winter in North America. Information about these and other community events is available on the CNCF [events](https://www.cncf.io/events/) pages. From c2006e201899112f1f4223c895f00a3f5c24af3b Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Thu, 16 Nov 2017 15:00:01 -0800 Subject: [PATCH 08/10] updating KubeCon information --- contributors/guide/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index ced975a2da8..a83258d9fb1 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -192,8 +192,7 @@ _Improvements needed_ * The top level k/community/README.md should be a good starting point for what the community is and does. (see above instructions on rewriting this file) ## Events - -Kubernetes is the main focus of CloudNativeCon/KubeCon, held every spring in Europe and winter in North America. Information about these and other community events is available on the CNCF [events](https://www.cncf.io/events/) pages. +Kubernetes is the main focus of CloudNativeCon/KubeCon, held twice per year in EMEA and in North America. Information about these and other community events is available on the CNCF [events](https://www.cncf.io/events/) pages. ### Meetups @@ -201,7 +200,7 @@ __Improvements needed_ * include link to meetups * information on CNCF support for founding a Meetup -### Kubecon +### KubeCon _Improvements needed_ * write friendly blurb about KubeCon, and include links From 05c21e2f2741d2e79bf139623be11d56cfd88265 Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Mon, 20 Nov 2017 09:01:42 -0800 Subject: [PATCH 09/10] redirect links and formatting --- contributors/guide/README.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index a83258d9fb1..1824fe07ea2 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -1,15 +1,14 @@ **OWNER:** -SIG-ContribX +sid-contributor-experience - -# WARNING +## Disclaimer Hello! This is the starting point for our brand new contributor guide, currently underway as per [-issue#6102](https://github.com/kubernetes/website/issues/6102) and in need of help. Please be patient, or fix a section below that needs improvement, and submit a pull request! Many of the links below should lead to relevant documents scattered across the community repository. Often, the linked instructions need to be updated or cleaned up. -* If you do so, please port the relevant file from its previous location to come live in the community/contributors/guide folder, and delete its previous location. -* Ultimately, all contributor guide specific files will live in this folder. +* If you do so, please move the relevant file from its previous location to the community/contributors/guide folder, and delete its previous location. +* Our goal is that all contributor guide specific files live in this folder. Please find _Improvements needed_ sections below and help us out. @@ -34,7 +33,7 @@ Welcome to Kubernetes! This document is the single source of truth for how to co ## Sign the CLA -Before you can contribute, you will need to sign the [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md). +Before you can contribute, you will need to sign the [Contributor License Agreement](https://git.k8s.io/community/CLA.md). ## Setting up your development environment @@ -63,7 +62,7 @@ For a brief description of the importance of code review, please read [On Code R _Improvements needed_ * edit above link to only provide code review section. -* decide whether this is something that belongs in this section, or should be combined with Contributing instructions [below](https://github.com/guineveresaenger/community/tree/contributor-guide/contributors/guide#contributing). +* decide whether this is something that belongs in this section, or should be combined with Contributing instructions [below](/contributor-guide/contributors/guide#contributing). ### Thanks @@ -115,42 +114,42 @@ _Improvements needed_ * Possible text to elaborate on (the sig list should remain in its current place however): - * ([Pick a SIG](https://github.com/kubernetes/community/blob/master/sig-list.md), peruse its associated [cmd](https://github.com/kubernetes/kubernetes/tree/master/cmd) directory, find a main() and read code until you find something you want to fix.) + * ([Pick a SIG](https://git.k8s.io/community/sig-list.md), peruse its associated [cmd](https://git.k8s.io/kubernetes/cmd) directory, find a main() and read code until you find something you want to fix.) ### File an Issue Not ready to contribute code, but see something that needs work? While we encourage everyone to contribute code, we also appreciate it when someone finds a problem. Again, there are multiple repositories within the community, and each will have its own Issues. -For example, here is where you file an Issue to [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/issues/new). Please make sure to adhere to the prompted submission guidelines. +For example, here is where you file an Issue to [kubernetes/kubernetes](https://git.k8s.io/kubernetes/issues/new). Please make sure to adhere to the prompted submission guidelines. _Improvements needed_ * clarify there are many k/subrepos where you can file issues. Refer to "how to find and appropriate SIG" document to find out which. # Contributing -(From:[here](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md)) +(From:[here](https://git.k8s.io/community/contributors/devel/collab.md)) Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be "at work" effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully these rules make things go more smoothly. If you find that this is not the case, please complain loudly. As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a PR. -Our community guiding principles on how to create great code as a big group are found [here](https://github.com/kubernetes/community/blob/master/contributors/devel/collab.md#code-reviews). +Our community guiding principles on how to create great code as a big group are found [here](https://git.k8s.io/community/contributors/devel/collab.md#code-reviews). If you haven't done so already make sure you have found the correct SIG for your contribution. This will ensure faster responses and a streamlined code review. (see above) _Improvements needed_ -* the linked text is awfully similar to the section on [Code Review](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review), linked above. Consolidate, and decide on _one place_ in this document where it fits best. It might even be important enough to include at top level in this document(no links). +* the linked text is awfully similar to the section on [Code Review](https://git.k8s.io/community/contributors/devel/community-expectations.md#code-review), linked above. Consolidate, and decide on _one place_ in this document where it fits best. It might even be important enough to include at top level in this document(no links). ### Communication It is best to contact your SIG for issues related to the SIG's topic. Your SIG will be able to help you much more quickly than a general question would. Each SIG has a kubernetes slack channel that you can join as well. -For questions and troubleshooting, please feel free to use any of the methods of communication listed [here](https://github.com/kubernetes/community/blob/master/communication.md). The [kubernetes website](https://kubernetes.io/community/) also lists this information. +For questions and troubleshooting, please feel free to use any of the methods of communication listed [here](https://git.k8s.io/community/communication.md). The [kubernetes website](https://kubernetes.io/community/) also lists this information. ## GitHub workflow -To check out code to work on, please refer to [this guide](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#workflow). +To check out code to work on, please refer to [this guide](https://git.k8s.io/community/contributors/devel/development.md#workflow). _Improvements needed_ @@ -158,12 +157,12 @@ _Improvements needed_ ## Open a PR -PR workflow is described [here](https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#the-testing-and-merge-workflow). +PR workflow is described [here](https://git.k8s.io/community/contributors/devel/pull-requests.md#the-testing-and-merge-workflow). ## Code Review _Improvements needed_ -* Clarify and streamline some of the explanations from [here](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md#code-review-process). +* Clarify and streamline some of the explanations from [here](https://git.k8s.io/community/contributors/devel/owners.md#code-review-process). * Explain OWNERS files and process (also found in above link) @@ -185,7 +184,7 @@ _Improvements needed_ # Community -If you haven't noticed by now, we have a large, lively, and friendly open-source community. We depend on new people becoming members and regular code contributors, so we would like you to come join us. To find out more about our community structure, different levels of membership and code contributors, please [explore here](https://github.com/kubernetes/community/blob/master/community-membership.md). +If you haven't noticed by now, we have a large, lively, and friendly open-source community. We depend on new people becoming members and regular code contributors, so we would like you to come join us. To find out more about our community structure, different levels of membership and code contributors, please [explore here](https://git.k8s.io/community/community-membership.md). _Improvements needed_ @@ -196,7 +195,7 @@ Kubernetes is the main focus of CloudNativeCon/KubeCon, held twice per year in E ### Meetups -__Improvements needed_ +_Improvements needed_ * include link to meetups * information on CNCF support for founding a Meetup From 6adfb9ea5b2bbf4b78528234c368574bf5bf07a5 Mon Sep 17 00:00:00 2001 From: guineveresaenger Date: Mon, 20 Nov 2017 09:10:09 -0800 Subject: [PATCH 10/10] final redirects --- contributors/guide/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contributors/guide/README.md b/contributors/guide/README.md index 1824fe07ea2..3db0bf1ce52 100644 --- a/contributors/guide/README.md +++ b/contributors/guide/README.md @@ -58,7 +58,7 @@ Please make sure to read and observe our [Code of Conduct](https://github.com/cn ### Code Review -For a brief description of the importance of code review, please read [On Code Review](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md#code-review). +For a brief description of the importance of code review, please read [On Code Review](https://git.k8s.io/community/contributors/devel/community-expectations.md#code-review). _Improvements needed_ * edit above link to only provide code review section. @@ -70,14 +70,14 @@ Many thanks in advance to everyone who contributes their time and effort to maki # Your First Contribution -(from [here](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#introduction)) +(from [here](https://git.k8s.io/community/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#introduction)) Have you ever wanted to contribute to the coolest cloud technology? We will help you understand the organization of the Kubernetes project and direct you to the best places to get started. You'll be able to pick up issues, write code to fix them, and get your work reviewed and merged. If you have questions about the development process, feel free to jump into our [Slack Channel](http://slack.k8s.io/) or join our [mailing list](https://groups.google.com/forum/#!forum/kubernetes-dev). _Improvements needed_ -* The doc linked [above](https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#introduction) is being reinvented in this README. All relevant information should be ported to a logical place in this document/folder, and the original document deleted. +* The doc linked [above](https://git.k8s.io/community/contributors/devel/welcome-to-kubernetes-new-developer-guide.md#introduction) is being reinvented in this README. All relevant information should be ported to a logical place in this document/folder, and the original document deleted. ## Find something to work on @@ -104,7 +104,7 @@ Here is how (_information needed_) _Improvements needed_ * Clarify how someone would find the correct SIG, and what to do with that information. Link to those SIGs. -* [This paragraph](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about a PR not associated with an open issue? +* [This paragraph](https://git.k8s.io/community/contributors/devel/issues.md#find-the-right-sigs) helps to find the SIG for an existing issue; what about a PR not associated with an open issue? * Make people aware of “extra” contributing guidelines on a SIG.