From 01b165e6dd2afbd1f71d29f7c2d8295d7b072539 Mon Sep 17 00:00:00 2001 From: Jeffrey Regan Date: Mon, 6 Mar 2017 09:21:47 -0800 Subject: [PATCH] Close kubernetes/community#420 * Move remaining community stuff out of kubernetes/kubernetes/README so that there's only one thing to maintain. * Put self-contained things into their own MD files. * Have other docs point to those files rather than attempt to repeat their content. * Make all docs smaller. See also companion PR in kubernetes/community. --- CONTRIBUTING.md | 133 ++---------------------------------------------- README.md | 97 +++++++++++++++++------------------ 2 files changed, 53 insertions(+), 177 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d98956f974b3..470f556adfd7a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,132 +1,9 @@ -# Contributing guidelines - -Want to hack on Kubernetes? Yay! - -## Developer Guide - -We have a [Developer's Guide](docs/devel/README.md) that outlines everything -you need to know from setting up your dev environment to how to get faster Pull -Request reviews. If you find something undocumented or incorrect along the way, -please feel free to send a Pull Request. - -## Filing issues - -If you have a question about Kubernetes or have a problem using it, please -start with the [troubleshooting guide](http://kubernetes.io/docs/troubleshooting/). If that -doesn't answer your questions, or if you think you found a bug, please [file an -issue](https://github.com/kubernetes/kubernetes/issues/new). - -## How to become a contributor and submit your own code - -### Contributor License Agreements - -We'd love to accept your patches! Before we can take them, we have to jump a -couple of legal hurdles. - -The Cloud Native Computing Foundation (CNCF) CLA [must be signed](https://github.com/kubernetes/community/blob/master/CLA.md) by all contributors. -Please fill out either the individual or corporate Contributor License -Agreement (CLA). - -Once you are CLA'ed, we'll be able to accept your pull requests. For any issues that you face during this process, -please add a comment [here](https://github.com/kubernetes/kubernetes/issues/27796) explaining the issue and we will help get it sorted out. - -***NOTE***: Only original source code from you and other people that have -signed the CLA can be accepted into the repository. This policy does not -apply to [third_party](third_party/) and [vendor](vendor/). - -### Finding Things That Need Help - -If you're new to the project and want to help, but don't know where to start, -we have a semi-curated list of issues that have should not need deep knowledge -of the system. [Have a look and see if anything sounds -interesting](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted). - -Alternatively, read some of the many docs on the system, for example [the -architecture](docs/design/architecture.md), and pick a component that seems -interesting. Start with `main()` (look in the [cmd](cmd/) directory) and read -until you find something you want to fix. The best way to learn is to hack! -There's always code that can be clarified and variables or functions that can -be renamed or commented. - -### Contributing A Patch - -If you're working on an existing issue, such as one of the `help-wanted` ones -above, simply respond to the issue and express interest in working on it. This -helps other people know that the issue is active, and hopefully prevents -duplicated efforts. - -If you want to work on a new idea of relatively small scope: - -1. Submit an issue describing your proposed change to the repo in question. -1. The repo owners will respond to your issue promptly. -1. If your proposed change is accepted, and you haven't already done so, sign a - Contributor License Agreement (see details above). -1. Fork the repo, develop, and test your changes. -1. Submit a pull request. - -If you want to work on a bigger idea, we STRONGLY recommend that you start with -some bugs or smaller features. We have a [feature development -process](https://github.com/kubernetes/features/blob/master/README.md), but -navigating the Kubernetes system as a newcomer can be very challenging. - -### Downloading the project - -There are a few ways you can download this code. You must download it into a -GOPATH - see [golang.org](https://golang.org/doc/code.html) for more info on -how Go works with code. This project expects to be found at the Go package -`k8s.io/kubernetes`. - -1. You can `git clone` the repo. If you do this, you MUST make sure it is in - the GOPATH as `k8s.io/kubernetes` or it may not build. E.g.: `git clone - https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes` -1. You can use `go get` to fetch the repo. This will automatically put it into - your GOPATH in the right place. E.g.: `go get -d k8s.io/kubernetes` -1. You can download an archive of the source. If you do this, you MUST make - sure it is unpacked into the GOPATH as `k8s.io/kubernetes` or it may not - build. See [rel.k8s.io](http://rel.k8s.io) for a list of available releases. - -### Building the project - -There are a few things you need to build and test this project: - -1. `make` - the human interface to the Kubernetes build is `make`, so you must - have this tool installed on your machine. We try not to use too many crazy - features of `Makefile`s and other tools, so most commonly available versions - should work. -1. `docker` - some parts of the build/test system depend on `docker`. You - need a relatively recent version of Docker installed, and available to you. -1. `go` - Kubernetes is written in Go (aka golang), so you need a relatively - recent version of the [Go toolchain](https://golang.org/dl/) installed. - While Linux is the primary platform for Kubernetes, it should compile on a - Mac, too. Windows is in progress. - -To build Kubernetes, simply type `make`. This should figure out what it needs -to do and not need any input from you. If you want to just build a subset of -code, you can pass the `WHAT` variable to `make`: e.g. `make -WHAT="cmd/kubelet"`. - -To run basic tests, simply type `make test`. This will run all of the unit -tests in the project. If you want to just test a subset of the project, you -can pass the `WHAT` variable to `make`: e.g. `make test WHAT=pkg/kubelet`. - -### Protocols for Collaborative Development - -Please read [this doc](docs/devel/collab.md) for information on how we're -running development for the project. Also take a look at the [development -guide](docs/devel/development.md) for information on how to set up your -environment, run tests, manage dependencies, etc. - -### Adding dependencies - -If your patch depends on new packages, add that package with -[`godep`](https://github.com/tools/godep). Follow the [instructions to add a -dependency](docs/devel/development.md#godep-and-dependency-management). - -### Community Expectations - -Please see our [expectations](docs/devel/community-expectations.md) for members -of the Kubernetes community. +# Contributing +Information about contributing to the +[kubernetes code repo](README.md) lives in the +[kubernetes community repo](https://github.com/kubernetes/community) +(it's a big topic). [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/CONTRIBUTING.md?pixel)]() diff --git a/README.md b/README.md index 85cce4674ff02..155d62a5c4a28 100644 --- a/README.md +++ b/README.md @@ -4,60 +4,42 @@ -[Submit Queue]: http://submit-queue.k8s.io/#/e2e -[Submit Queue Widget]: http://submit-queue.k8s.io/health.svg?v=1 -[GoDoc]: https://godoc.org/k8s.io/kubernetes -[GoDoc Widget]: https://godoc.org/k8s.io/kubernetes?status.svg - -## Introduction - -Kubernetes is an open source system for managing [containerized applications](http://kubernetes.io/docs/whatisk8s/) across multiple hosts, -providing basic mechanisms for deployment, maintenance, and scaling of applications. Kubernetes is hosted by the Cloud Native Computing Foundation ([CNCF](https://www.cncf.io)). - -Kubernetes builds upon a decade and a half of experience at Google running production workloads at scale using a system called [Borg](https://research.google.com/pubs/pub43438.html), combined with best-of-breed ideas and practices from the community. - -
- -### Are you ... - - * Interested in learning more about using Kubernetes? - - See our documentation on [kubernetes.io](http://kubernetes.io). - - Try our [interactive tutorial](http://kubernetes.io/docs/tutorials/kubernetes-basics/). - - Take a free course on [Scalable Microservices with Kubernetes](https://www.udacity.com/course/scalable-microservices-with-kubernetes--ud615). - * Interested in developing the core Kubernetes code base, developing tools using the Kubernetes API or helping in anyway possible? Keep reading! +---- -## Code of Conduct +Kubernetes is an open source system for managing [containerized applications] +across multiple hosts, providing basic mechanisms for deployment, maintenance, +and scaling of applications. -The Kubernetes community abides by the CNCF [code of conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). Here is an excerpt: +Kubernetes builds upon a decade and a half of experience at Google running +production workloads at scale using a system called [Borg], +combined with best-of-breed ideas and practices from the community. -_As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities._ +Kubernetes is hosted by the Cloud Native Computing Foundation ([CNCF]). +If you are a company that wants to help shape the evolution of +technologies that are container-packaged, dynamically-scheduled +and microservices-oriented, consider joining the CNCF. +For details about who's involved and how Kubernetes plays a role, +read the CNCF [announcement]. -## Community +---- -Do you want to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented?. If you are a company, you should consider joining the [CNCF](https://cncf.io/about). For details about who's involved in CNCF and how Kubernetes plays a role, read [the announcement](https://cncf.io/news/announcement/2015/07/new-cloud-native-computing-foundation-drive-alignment-among-container). For general information about our community, see the website [community](http://kubernetes.io/community/) page. +## To start using Kubernetes -* Join us on social media ([Twitter](https://twitter.com/kubernetesio), [Google+](https://plus.google.com/u/0/b/116512812300813784482/116512812300813784482)) and read our [blog](http://blog.kubernetes.io/). -* Ask questions and help answer them on [Slack](http://slack.k8s.io/) or [Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes). -* Attend our key events ([kubecon](http://events.linuxfoundation.org/events/kubecon), [cloudnativecon](http://events.linuxfoundation.org/events/cloudnativecon), weekly [community meeting](https://github.com/kubernetes/community/blob/master/community/README.md)). -* Join a Special Interest Group ([SIG](https://github.com/kubernetes/community)). +See our documentation on [kubernetes.io]. -## Contribute +Try our [interactive tutorial]. -If you're interested in being a contributor and want to get involved in developing Kubernetes, get started with this reading: +Take a free course on [Scalable Microservices with Kubernetes]. -* The community [expectations](https://github.com/kubernetes/community/blob/master/contributors/devel/community-expectations.md) -* The [contributor guidelines](CONTRIBUTING.md) -* The [Kubernetes Developer Guide](https://github.com/kubernetes/community/tree/master/contributors/devel) +## To start developing Kubernetes -You will then most certainly gain a lot from joining a [SIG](https://github.com/kubernetes/community), attending the regular hangouts as well as the community [meeting](https://github.com/kubernetes/community/blob/master/community/README.md). - -If you have an idea for a new feature, see the [Kubernetes Features](https://github.com/kubernetes/features) repository for a list of features that are coming in new releases as well as details on how to propose one. - -### Building Kubernetes for the impatient +The [community repository] hosts all information about +building Kubernetes from source, how to contribute code +and documentation, who to contact about what, etc. If you want to build Kubernetes right away there are two options: -* You have a working [Go environment](https://golang.org/doc/install). +##### You have a working [Go environment]. ``` $ go get -d k8s.io/kubernetes @@ -65,7 +47,7 @@ $ cd $GOPATH/src/k8s.io/kubernetes $ make ``` -* You have a working [Docker environment](https://docs.docker.com/engine/). +##### You have a working [Docker environment]. ``` $ git clone https://github.com/kubernetes/kubernetes @@ -73,15 +55,32 @@ $ cd kubernetes $ make quick-release ``` -If you are less impatient, head over to the [developer's documentation](https://github.com/kubernetes/community/tree/master/contributors/devel). +If you are less impatient, head over to the [developer's documentation]. ## Support -While there are many different channels that you can use to get hold of us ([Slack](http://slack.k8s.io/), [Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes), [Issues](https://github.com/kubernetes/kubernetes/issues/new), [Forums/Mailing lists](https://groups.google.com/forum/#!forum/kubernetes-users)), you can help make sure that we are efficient in getting you the help that you need. - -If you need support, start with the [troubleshooting guide](http://kubernetes.io/docs/troubleshooting/) and work your way through the process that we've outlined. - -That said, if you have questions, reach out to us one way or another. We don't bite! +If you need support, start with the [troubleshooting guide] +and work your way through the process that we've outlined. + +That said, if you have questions, reach out to us +[one way or another][communication]. + +[announcement]: https://cncf.io/news/announcement/2015/07/new-cloud-native-computing-foundation-drive-alignment-among-container +[Borg]: https://research.google.com/pubs/pub43438.html +[CNCF]: https://www.cncf.io/about +[communication]: https://github.com/kubernetes/community/blob/master/communication.md +[community repository]: https://github.com/kubernetes/community +[containerized applications]: http://kubernetes.io/docs/whatisk8s +[developer's documentation]: https://github.com/kubernetes/community/tree/master/contributors/devel +[Docker environment]: https://docs.docker.com/engine +[Go environment]: https://golang.org/doc/install +[GoDoc]: https://godoc.org/k8s.io/kubernetes +[GoDoc Widget]: https://godoc.org/k8s.io/kubernetes?status.svg +[interactive tutorial]: http://kubernetes.io/docs/tutorials/kubernetes-basics +[kubernetes.io]: http://kubernetes.io +[Scalable Microservices with Kubernetes]: https://www.udacity.com/course/scalable-microservices-with-kubernetes--ud615 +[Submit Queue]: http://submit-queue.k8s.io/#/e2e +[Submit Queue Widget]: http://submit-queue.k8s.io/health.svg?v=1 +[troubleshooting guide]: http://kubernetes.io/docs/troubleshooting [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/README.md?pixel)]() -