Umbrella issue for contributor's guide

[guineveresaenger]

As per https://github.com/kubernetes/website/issues/6102 we need a contributor guide that is easily found, complete, and organized logically.

In https://github.com/kubernetes/community/pull/1409, a /guide folder is being created in k/community/contributors, and its README is set up to be the central starting point for contributing.

This issue is an umbrella tracking issue. Below is a list of check boxes for individual items that need fixing. Some are easy, others require some expertise/experience as a contributor.

To help out:

1. Pick a checkbox item. You will find prompts in the README to where these improvements are needed; they should mostly parallel these check points.
2. Ping me or this issue so I can update this comment next to the checkpoint to say that you are working on this.
3. When finished with the item, submit a PR. In many cases, we will want to re-write, move, and/or remove a linked reference. This should be reflected in the PR. All contributing specific information (i.e. GitHub workflow) should ultimately live in k/community/contributors/guide. The ultimate goal is to have a single source of truth for all these topics.
4. Comment on your PR with a note like "...in partial completion of..." and refer to this issue.
5. Follow up with me to make sure I crossed off the checkbox as completed.

Pages to Update: https://github.com/kubernetes/community/tree/master/contributors/guide/README.md https://github.com/kubernetes/community/tree/master/contributors/guide

List of tasks

• [x] kubernetes/kubernetes/contributing.md -> point to community/contributors/guide/README.md Thank you, @anubhakushwaha!

• [x] kubernetes/community/CONTRIBUTING.md -> Needs a rewrite to reflect only k/community-specific contributing guidelines

• [x] kubernetes/community/README.md -> Needs a rewrite to talk about k/community specifically and what it does

• [x] Individual SIG contributing documents -> add a link to community/contributors/guide/README.md List of SIGs with contributing docs in comment below.

• [x] Generate TOC for community/contributors/guide/README.md

• [x] Document should point at developer guide being worked on by RyanJ from RedHat (?) @castrojo there's a link to resources pointing at top level README in /devel

• [x] consolidate the Code Review principles from several sources, and find a good place in /guide/README.md where it flows best

• [x] This README will reinvent the contributor's guide. Ensure all relevant information from https://github.com/kubernetes/community/blob/master/contributors/devel/welcome-to-kubernetes-new-developer-guide.md (Edit: this file has been incorporated)and https://github.com/kubernetes/community/blob/master/contributors/devel/development.md has been correctly ported and the original files deprecated (see additional task list below)

• [x] Clarify help-wanted issues also exist on projects other than k/kubernetes, e.g. k/kubectl.

• [x] Clarify how someone would find the correct SIG, and what to do with that information. Link to those SIGs.

• [x] This paragraph helps to find the SIG for an existing issue; what about a PR not associated with an open issue? Clarify/link/rewrite.

• [x] Make reader aware each SIG may have special additional contributing guidelines

• [x] Possible text to elaborate on (the sig list should remain in its current place however): Pick a SIG, peruse its associated cmd directory, find a main() and read code until you find something you want to fix.

• [x] clarify there are many k/subrepos where you can file issues. Refer to "how to find an appropriate SIG" document to find out which.

• [x] move github workflow into its own file in this folder. edit; working on this currently 1/2

• [x] Clarify and streamline some of the code review explanations from here. Explain OWNERS files and process. Thank you to @tpepper for this!

• [x] Create (or find) and link to a document that explains kubernetes testing, how to use it, where to find test output, explain debugging, etc. Also link to testing pipelines.

• [x] Create Security subsection of Contributing section @castrojo will follow and create issue

• [x] Provide link and starter kit contact/packet for Kubernetes Meetups

• [x] Provide description and link for Kubernetes Pilots.

• [x] Move contributor cheatsheet to /guide folder

• [x] We have an area/contributor-guide label now, we can tag all the issues with that and just link to it once from the main contributor guide readme instead of inlining tasks in the document itself, this will clean up the index considerably.

/sig contribex

Files to scrub

Each of these files in the contributors/devel needs to be scrubbed for the contributor guide. As they are finished they should be moved over to contributors/guide. Non-contributor relevant topics should remain in contributors/devel, so there are some calls to make.

They are written by multiple people and might contain years of cruft, check for:

• Duplicate content that can be removed, so for example, don't leave in a copy of the CoC, change it to a link to the canonical URL in here.
• Might not be appropriate for the contributor guide (mark it off and add a reason)
• Might need to be ouright be deleted or combined with another document :D
• Might be blocked on waiting on another part of the contributor guide to be finished.

Working list

• [x] adding-an-APIGroup.md - Should be part of developer guide
• [x] api-conventions.md - Should be part of developer guide
• [x] api_changes.md - Should be part of developer guide
• [x] architectural-roadmap.md - Should be part of developer guide and/or SIG Arch
• [x] automation.md - Should not be part of the developer guide - also needs update. Possibly live in k/test-infra?
• [x] bazel.md - Not default yet, skip for now?
• [x] cherry-picks.md - Should be part of the guide, but where? - move to https://git.k8s.io/sig-release/release-process-documentation
• [x] client-libraries.md - Moved to docs
• [x] coding-conventions.md - In progress moved to contributors guide
• [x] collab.md - Do not migrate, consider deletion
• [x] community-expectations.md - Moved to contrib guide
• [x] component-config-conventions.md - This feels like a design document, skip
• [x] container-runtime-interface.md - Should be moved into docs.
• [x] contributor-cheatsheet.md - Moved to contrib guide
• [x] controllers.md - This feels like a design document, skip
• [x] cri-container-stats.md - Skip
• [x] cri-validation.md - Skip
• [x] development.md - Should be part of developer guide but needs cleaning up: #1756
• [x] e2e-node-tests.md - Skip
• [x] e2e-tests.md - Skip
• [x] faster_reviews.md merged with pull requests
• [x] flaky-tests.md - Skip
• [x] flexvolume.md - Should be part of developer guide
• [x] generating-clientset.md - Should be part of developer guide
• [x] getting-builds.md - Should be part of developer guide
• [x] github-workflow.md - Moved to contrib guide
• [x] github_workflow.png - Moved to contrib guide
• [x] go-code.md - Has been moved to coding convertions.md in contributor guide
• [x] godep.md - Skip
• [x] gubernator-images - Seems removed for good
• [x] gubernator.md - Should be part of developer guide
• [x] help-wanted.md - Should be part of another contributor guide doc; it is also not linked from anywhere: #1757
• [x] how-to-doc.md - Should be part of developer guide
• [x] instrumentation.md Should be part of developer guide
• [x] issues.md - In progress moved to contrib guide
• [x] kubectl-conventions.md - Should be part of developer guide
• [x] kubelet-cri-networking.md - Should be part of developer guide
• [x] kubemark-guide.md - Should be part of developer guide
• [x] logging.md - Skip (also it looks very old and not too useful)
• [x] mesos-style.md - Should be part of developer guide
• [x] node-performance-testing.md - Skip, should be part of an operator's guide.
• [x] on-call-federation-build-cop.md - Skip, should be part of some testing guide?
• [x] OWNERS
• [x] owners.md - Moved to contributors guide
• [x] profiling.md - Should be part of developer guide
• [x] pr_workflow.dia skip - see below
• [x] pr_workflow.png skip - seems inaccurate and confusing
• [x] pull-requests.md - Will be done in issue #1514
• [x] README.md
• [x] release
• [x] running-locally.md - this should probably be deleted.
• [x] scalability-good-practices.md - moved to contributor guide
• [x] scheduler_algorithm.md - Should be part of developer guide
• [x] scheduler.md - Should be part of developer guide
• [x] security-release-process.md - already moved to release process guide(s)
• [x] staging.md
• [x] strategic-merge-patch.md - Should be part of developer guide
• [x] testing.md - (Not sure on this one?)
• [x] update-release-docs.md - Should be moved to contributor guide
• [x] updating-docs-for-feature-changes.md - Should be moved to contributor guide
• [x] vagrant.md - Should stay in devel guide as part of a "setting up your client" document
• [x] welcome-to-kubernetes-new-developer-guide.md - Already moved/integrated
• [x] writing-a-getting-started-guide.md - Already moved/integrated
• [x] writing-good-e2e-tests.md - Skip

[guineveresaenger]

/sig contribex

[xiangpengzhao]

@guineveresaenger this is awesome!

BTW, I help modify the markdown format of the issue body to make the task list have checkbox. It might be more readable :)

[tpepper]

@guineveresaenger in the issue description the "pages to update" section has two links .../contributing/guide/ and I'm wondering if it should be .../contributors/guide as that's what's referenced earlier in the text and those pages do exist via #1409

[idvoretskyi]

cc @castrojo @parispittman

[anubhakushwaha]

@guineveresaenger I am new to this community and was really interested in helping with some tasks. For the beginning, I have added the link to community/contributors/guide/README.md in kubernetes/kubernetes/contributing.md , let me know if something else was desired and I will be happy to work upon the changes. Thank you.

[guineveresaenger]

Somebody please reopen this? I’m on mobile rn @castrojo

[cblecker]

@guineveresaenger already done :)

[guineveresaenger]

This is the of SIGs with CONTRIBUTING.md docs that should be updated to refer to this guide and clarify SIG-specific guidelines.

• [x] AWS SIG
• [x] SIG-cli
• [x] Multicluster SIG
• [x] Storage SIG

[castrojo]

Note to selves, we do not need to bring collab.md over from the devel directory, I have added it to the community expectations, and filed #1645 to remember to put what's left of it somewhere else.

[tpepper]

I started looking through from the end of the list at some test related devel/ docs and their linked docs. Based on that I think:

coding-conventions.md and go-code.md should move from devel to guide as they've broadly informative to new comers

testing.md, writing-good-e2e-tests.md, flaky-tests.md, e2e-tests.md, e2e-node-tests.md, and godep.md should stay in devel as they're notably deeper technically

I'm looking at a PR for these and a few small cleanups I've come across.

[guineveresaenger]

@castrojo - to add another note to selves, "community-expectations" is gone from current master branch and contains some useful information (although not sure the information in it is up to date).

[castrojo]

You mean this one? https://github.com/kubernetes/community/blob/master/contributors/guide/community-expectations.md

[castrojo]

We should review this for ideas: https://github.com/kubernetes-helm/community/pull/2/files

[castrojo]

/help

[k8s-ci-robot]

@castrojo: This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-help command.

In response to [this](https://github.com/kubernetes/community/issues/1413): >/help Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/devel/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.

[tpepper]

I propose "cherry-picks.md" not be in the contrib guide and rather move to https://git.k8s.io/sig-release/release-process-documentation

[guineveresaenger]

@tpepper noted, above

[guineveresaenger]

@tpepper others seem to agree - the doc in /devel is a duplicate; https://github.com/kubernetes/sig-release/blob/master/ephemera/cherry-picks.md

[ryanj]

Thanks to @guineveresaenger for showing me this issue. I've created a similar umbrella issue for documenting planned updates to the Developer guide (#1919)

[guineveresaenger]

I'd recommend that the remaining files in need of grooming be moved to #1919 since they are more on the technical side of things.

[guineveresaenger]

As of PR https://github.com/kubernetes/community/pull/2444 which merged earlier today, I pronounce this issue closed.

We have a working contributor guide! Yaaaay!

Thank you everyone for your hard work and support in pushing this through and using and promoting the guide when helping new contributors, especially @parispittman, @castrojo, @cblecker, @tpepper, @carolynvs, @nikhita, @idvoretskyi and everyone in sig contributor-experience. I'm sure I forgot some folks.