New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Umbrella issue for developer's guide updates #1919

Open
ryanj opened this Issue Mar 11, 2018 · 15 comments

Comments

@ryanj

ryanj commented Mar 11, 2018

As per kubernetes/website#6102, and #1413 we need a developers' guide that is easily found, complete, and organized logically.

I'll plan on documenting next-steps in this umbrella issue.

@idvoretskyi

This comment has been minimized.

Member

idvoretskyi commented Mar 12, 2018

@zacharysarah

This comment has been minimized.

Contributor

zacharysarah commented Mar 12, 2018

@parispittman

This comment has been minimized.

Contributor

parispittman commented Mar 12, 2018

Thanks for this, @ryanj

/sig contributor-experience

@ryanj

This comment has been minimized.

ryanj commented Mar 14, 2018

Looking into these first:

  • Establish a top-level Readme
  • adding-an-APIGroup.md - Should be part of developer guide
  • api-conventions.md - Should be part of developer guide
  • api_changes.md - Should be part of developer guide
  • architectural-roadmap.md - Should be part of developer guide and/or SIG Arch
  • include links to examples and step-by-step guides
@heckj

This comment has been minimized.

Member

heckj commented Mar 20, 2018

I think there would be a lot of value (and positive uptake, as well as inevitable bike-shedding) on having an example walk-through on "how to set up a dev environment, compile the code, run the tests, and see the tests pass". This doesn't exist to my experience, or is heavily tribal knowledge, and may even vary quite significantly between subprojects within Kubernetes (i.e. kubernetes/helm vs. kubernetes/kubernetes vs. kubernetes/minikube).

@carlpett

This comment has been minimized.

carlpett commented Mar 21, 2018

@heckj Agreed! As someone who just tried to get started with Kubernetes development this week, there are quite a few areas where the docs are either hard to find, or do not exist. Asking on Slack provided some answers, and experimentation filled in a few blanks. I'm probably still doing some things wrong...

I have notes of some gotchas I experienced, and would in general be happy to help writing some docs to make the onboarding easier!

@parispittman

This comment has been minimized.

Contributor

parispittman commented Mar 21, 2018

@carlpett - appreciate if you could list some of those missing pieces here so we can make sure to include/address. thanks for the help!

@carlpett

This comment has been minimized.

carlpett commented Mar 21, 2018

Of course!

This is in "chronological order of surprise" from the last few days :)

  • Import paths: k8s.io/X maps to github.com/kubernetes/kubernetes/staging/X. This is then found by the compiler because there are symlinks in vendor/k8s.io. Unexpected to someone used to Golang. (This is documented in staging/README.md, but you'll only find that if you know what you are looking for)
  • Making changes: There are a lot of places that need to be changed to make a change in a type, which seems to be required for many patches. After a while I got directed on Slack to api_changes.md, which covers it, but also a lot of other things. Perhaps a split it out, or have a simple version near the top of the document? api_changes.md also isn't linked from any of the other documentation pages, so it is not easy to find (there are 57 .md files in that directory).
  • Generating files: There are a lot of different file generation things going on. make generated_files does some of them, but there are also a number of other generator scripts under ./hack/. This is also mentioned in api_changes.md, if you find it and read far enough.
  • Building: There are no mentions of how to build in the devel/development.md file, except a note that you can experimentally build with Bazel. You need to find build/README.md, where build/run.sh make is introduced. (It is not clear what happens if you just run make. It seemed to hang on my machine, not sure if it is meant to work or not)
  • Running: If you do not want to run it directly on your machine, directions are unclear. It is mentioned that it is possible, but not how. If you do want to run it directly on your machine, there's a pretty long list of requirements, but still lacks version information (etcd is commonly only available in 2.x versions in the default package managers, for example, but 3.x is required to start, so you'll need to install it somehow)
  • More building: There are several other make targets that sometimes(?) need to be run. It's a bit confusing in in the docs when/if there should be run with make TARGET vs ./build/run.sh make TARGET. Would be great with some clear guidelines here.

As a wishlist for how the docs could have been structured in a way that I would have found intuitive, something like this (sort of a step-by-step style):

  • Prerequisites: Getting the code and development tools (not necessarily covering the "running" part here, just what you'll need to compile it)
  • Navigating the code base (what components live where, the gotcha regarding k8s.io/vendoring, ...)
  • Making a small change (some simple demonstration about what is required to do some typical first change)
  • Building your change (could have this before the change part, but since just compiling your change will take ~10-15 minutes, there's a high risk of losing people if they have to do it twice..)
  • Running your changed Kubernetes (might be merged with the previous one? Will get long, though...)
  • Adding a test
  • Making a PR
  • (Quick start: Alternative route for the impatient/short summary for reference - commands required to get up and running, etc)

Having a few different tutorials/model PRs for making changes in different parts of the system might be a nice addition as well.

@stealthybox

This comment has been minimized.

stealthybox commented May 4, 2018

I believe the proper git remote setup is documented, but it's worth noting in the guide that certain scripts (like hack/cherry_pick_pull.sh) actually depend on it.

@stealthybox

This comment has been minimized.

stealthybox commented May 4, 2018

Here's the kubeadm vagrant setup that we mentioned in the sig-contributor-experience deep dive at KubeCon EU:

kubernetes/kubeadm#780

It's a simple, portable workflow for building and testing kubeadm specifically.
I believe we can learn from it, since this was a large gap for sig-cluster-lifecycle.

@ryanj

This comment has been minimized.

ryanj commented Jun 5, 2018

Sorry for the delay on this issue! I'm mostly blocked for another 2 weeks, but am hoping to loop back around to it afterwords. If anyone else wants to jump on this issue, feed free. I don't want to get in the way.

@cblecker cblecker added this to Tracking/Umbrella Issues in Contributor Experience Jun 5, 2018

@fejta-bot

This comment has been minimized.

fejta-bot commented Sep 3, 2018

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

@parispittman

This comment has been minimized.

Contributor

parispittman commented Sep 4, 2018

/remove-lifecycle stale

we need to prioritize this and find an owner

@tpepper

This comment has been minimized.

Contributor

tpepper commented Sep 4, 2018

I do want to focus on it post 1.12 release. I got pulled toward release duties right after KubeCon EU got me really excited about pushing devel guid improvements forward.

@nikhita

This comment has been minimized.

Member

nikhita commented Oct 8, 2018

xref: #892 - this issue also has a lot of useful discussion regarding a developer guide.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment