improve readme for contributor experience #36817

sebgoa · 2016-11-15T14:05:51Z

What this PR does / why we need it:

This improves the top-level README. Removes broken links, removes links to make you bounce to another page, adds proper links to docs.
Shuffles things around a bit and improves reading.

@kubernetes/contributor-experience

This change is

metral · 2016-11-15T15:43:02Z

This PR removes links to external community efforts around k8s, e.g. Awesome-Kubernetes & CoreKube etc. - (I started CoreKube).

Is it worth it to place these efforts in a separate page dedicated for community resources as folks still find these sorts of efforts helpful?

/cc @bgrant0607 @sarahnovotny

sebgoa · 2016-11-15T15:50:19Z

To plead my case, as I mentioned on twitter, I was doing a review of the README and when I hit the bottom I saw those links. CoreKube is really nice but the collections page is empty.

I pondered a lot on what to do with them, and then decided to remove them.

I think they would be better on the website. there is a big community page that needs lots of love. There is also a big Tools page that needs love as well.

metral · 2016-11-15T15:53:39Z

Makes total sense 👍 .

I'll defer to Brian or Sarah to suggest a more appropriate home for these sorts of pages.

bgrant0607 · 2016-11-15T17:47:52Z

cc @kubernetes/docs

bgrant0607 · 2016-11-15T18:01:05Z

Copying from slack:

I don't think we should link to community resources from kubernetes/README.md. We should find a place on kubernetes.io for them.

Files to remove:

CONTRIB.md
DESIGN.md
contrib/README.md
docs/warning.png
docs/roadmap.md
docs/troubleshooting.md
docs/whatisk8s.md (De-dupe http://kubernetes.io/docs/whatisk8s/ website#414)
www/README.md

bgrant0607 · 2016-11-15T18:17:30Z

README.md

-Kubernetes is an open source system for managing [containerized applications](https://github.com/kubernetes/kubernetes/wiki/Why-Kubernetes%3F#why-containers) across multiple hosts,
-providing basic mechanisms for deployment, maintenance, and scaling of applications.
+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 is:


Please remove these bullets.

bgrant0607 · 2016-11-15T18:18:51Z

README.md

+
+<hr>
+
+### Kubernetes is ready for Production !


I'd just remove this subsection.

bgrant0607 · 2016-11-15T18:19:00Z

README.md

+
+Since the Kubernetes 1.0 release in July 2015 Kubernetes is ready for your production workloads. Check the [case studies](http://kubernetes.io/case-studies/).
+
+### Kubernetes can run anywhere !


I'd just remove this subsection.

bgrant0607 · 2016-11-15T18:19:55Z

README.md

+### Are you ...
+
+  * Interested in learning more about using Kubernetes?  Please see our user-facing documentation on [kubernetes.io](http://kubernetes.io). Try our [interactive tutorial](http://kubernetes.io/docs/tutorials/kubernetes-basics/) or take a free course on [Scalable Microservices with Kubernetes](https://www.udacity.com/course/scalable-microservices-with-kubernetes--ud615).
+  * Interested in hacking on the core Kubernetes code base, developing tools using the Kubernetes API or helping in anyway possible ?  Keep reading!


or helping with the project

bgrant0607 · 2016-11-15T18:21:04Z

README.md


-## Concepts
+## Concepts Overview


Please remove this subsection.

bgrant0607 · 2016-11-15T18:22:44Z

README.md


-Kubernetes documentation is organized into several categories.
+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 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).


container-packaged
microservices-oriented

English is right-associative.

bgrant0607 · 2016-11-15T18:24:27Z

README.md

-### Are you ready to add to the discussion?
-
-We have presence on:
+Join us on social media and read our blog:


I'd prefer to link to kubernetes.io (e.g., http://kubernetes.io/community/) and keep this simpler. If some of this info isn't easily found there, we should fix that.

bgrant0607 · 2016-11-15T18:26:17Z

README.md


-If you're interested in being a contributor and want to get involved in developing Kubernetes, start in the [Kubernetes Developer Guide](docs/devel/README.md) and also review the [contributor guidelines](CONTRIBUTING.md).
+* [kubecon](http://events.linuxfoundation.org/events/kubecon)


Hmm. I don't see info about kubecon on kubernetes.io. That would be useful to fix.

bgrant0607 · 2016-11-15T18:26:59Z

README.md


-While there are many different channels that you can use to get ahold of us, you can help make sure that we are efficient in getting you the help that you need.
+*  The community [expectations](docs/devel/community-expectations.md)


@michelleN We'll need to update these links when the developer docs are moved.

bgrant0607 · 2016-11-15T18:28:03Z

README.md


-### Community resources
+## Documentation


There's a link to the doc site above, so I think we can just remove this section.

bgrant0607 · 2016-11-15T18:29:36Z

Thanks for the cleanup, @sebgoa!

sebgoa · 2016-11-15T19:58:38Z

Ok addressed all comments.

I kept some links in the community section, just made it a bit more compact. I will make sure to revisit once the kubernetes.io/community page gets in a better state.

Ideally I would like to add a simple build section once I get passed #36655 , showing how you can build k8s in two bash commands will be powerful.

sebgoa · 2016-11-15T20:01:44Z

I think we could also remove code-of-conduct.md since it is now a link to cncf. I am linking directly to it in the readme.

k8s-ci-robot · 2016-11-15T20:26:45Z

Jenkins verification failed for commit db98a18. Full PR test history.

The magic incantation to run this job again is @k8s-bot verify test this. Please help us cut down flakes by linking to an open flake issue when you hit one in your PR.

bgrant0607 · 2016-11-15T22:18:09Z

@sebgoa code-of-conduct.md is currently part of the repo template. If we remove it here, we should make a similar change to the template. philips may have an opinion on that.

bgrant0607 · 2016-11-15T22:19:09Z

Verify checks failed.
https://k8s-gubernator.appspot.com/build/kubernetes-jenkins/pr-logs/pull/36817/pull-kubernetes-verify/4754/

bgrant0607 · 2016-11-15T22:21:14Z

LGTM other than the check failures.

sebgoa · 2016-11-17T16:50:55Z

ok tests are passing now. hadn't run munge-docs so fixed some broken links in docs/ docs/devel and examples/ folders.

bgrant0607 · 2016-11-17T21:44:27Z

@saad-ali Would you mind if this were merged now?

saad-ali · 2016-11-18T05:12:45Z

@saad-ali Would you mind if this were merged now?

Doc changes are ok for post-code-freeze merge.

k8s-github-robot · 2016-11-18T05:30:00Z

Automatic merge from submit-queue

philips · 2016-11-22T19:41:00Z

I am fine with the code-of-conduct move. I will do the same for the template project.

Automatic merge from submit-queue improve readme for contributor experience **What this PR does / why we need it**: This improves the top-level README. Removes broken links, removes links to make you bounce to another page, adds proper links to docs. Shuffles things around a bit and improves reading. @kubernetes/contributor-experience

improve readme for contributor experience

ec02f3b

googlebot added the cla: yes label Nov 15, 2016

k8s-github-robot assigned brendandburns Nov 15, 2016

k8s-github-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. release-note-label-needed labels Nov 15, 2016

bgrant0607 added release-note-none Denotes a PR that doesn't merit a release note. and removed release-note-label-needed labels Nov 15, 2016

bgrant0607 assigned bgrant0607 and unassigned brendandburns Nov 15, 2016

bgrant0607 suggested changes Nov 15, 2016

View reviewed changes

Additional cleanups and addressing review

db98a18

fix munge-docs build errors

e0855ea

bgrant0607 approved these changes Nov 17, 2016

View reviewed changes

bgrant0607 added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 17, 2016

saad-ali added this to the v1.5 milestone Nov 18, 2016

k8s-github-robot merged commit 5143bae into kubernetes:master Nov 18, 2016

sebgoa deleted the readme branch November 18, 2016 08:30

sebgoa mentioned this pull request Nov 27, 2016

README improvements kubernetes-client/python#47

Merged

sebgoa mentioned this pull request Dec 9, 2016

Add build instructions for the impatient #38504

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

improve readme for contributor experience #36817

improve readme for contributor experience #36817

sebgoa commented Nov 15, 2016 •

edited

metral commented Nov 15, 2016 •

edited

sebgoa commented Nov 15, 2016

metral commented Nov 15, 2016 •

edited

bgrant0607 commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016 •

edited

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 Nov 15, 2016

michelleN Nov 15, 2016

bgrant0607 Nov 15, 2016

bgrant0607 commented Nov 15, 2016

sebgoa commented Nov 15, 2016

sebgoa commented Nov 15, 2016

k8s-ci-robot commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016

sebgoa commented Nov 17, 2016

bgrant0607 commented Nov 17, 2016

saad-ali commented Nov 18, 2016

k8s-github-robot commented Nov 18, 2016

philips commented Nov 22, 2016


		Since the Kubernetes 1.0 release in July 2015 Kubernetes is ready for your production workloads. Check the [case studies](http://kubernetes.io/case-studies/).

		### Kubernetes can run anywhere !


		Kubernetes documentation is organized into several categories.
		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 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).


		If you're interested in being a contributor and want to get involved in developing Kubernetes, start in the [Kubernetes Developer Guide](docs/devel/README.md) and also review the [contributor guidelines](CONTRIBUTING.md).
		* [kubecon](http://events.linuxfoundation.org/events/kubecon)


		While there are many different channels that you can use to get ahold of us, you can help make sure that we are efficient in getting you the help that you need.
		* The community [expectations](docs/devel/community-expectations.md)

improve readme for contributor experience #36817

improve readme for contributor experience #36817

Conversation

sebgoa commented Nov 15, 2016 • edited

metral commented Nov 15, 2016 • edited

sebgoa commented Nov 15, 2016

metral commented Nov 15, 2016 • edited

bgrant0607 commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Nov 15, 2016

sebgoa commented Nov 15, 2016

sebgoa commented Nov 15, 2016

k8s-ci-robot commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016

bgrant0607 commented Nov 15, 2016

sebgoa commented Nov 17, 2016

bgrant0607 commented Nov 17, 2016

saad-ali commented Nov 18, 2016

k8s-github-robot commented Nov 18, 2016

philips commented Nov 22, 2016

sebgoa commented Nov 15, 2016 •

edited

metral commented Nov 15, 2016 •

edited

metral commented Nov 15, 2016 •

edited

bgrant0607 commented Nov 15, 2016 •

edited