Skip to content
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 contributor's guide #1413

Closed
guineveresaenger opened this Issue Nov 16, 2017 · 21 comments

Comments

10 participants
@guineveresaenger
Copy link
Contributor

guineveresaenger commented Nov 16, 2017

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

In #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

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

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

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

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

  • Generate TOC for community/contributors/guide/README.md

  • 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

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

  • 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)

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

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

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

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

  • 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.

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

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

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

  • 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.

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

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

  • Provide description and link for Kubernetes Pilots.

  • Move contributor cheatsheet to /guide folder

  • 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

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

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Nov 16, 2017

/sig contribex

@xiangpengzhao

This comment has been minimized.

Copy link
Member

xiangpengzhao commented Nov 22, 2017

@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

This comment has been minimized.

Copy link
Contributor

tpepper commented Dec 6, 2017

@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

tpepper added a commit to tpepper/community that referenced this issue Dec 6, 2017

contributing guide: add initial section on testing
This commit replaces the "Improvements needed" marker for the testing
topic with an initial section of overview information and jumping off links
to sig-testing, test documentation, and test code.

Part of: kubernetes#1413

Signed-off-by: Tim Pepper <tpepper@vmware.com>

tpepper added a commit to tpepper/community that referenced this issue Dec 6, 2017

contributing guide: add initial section on testing
This commit replaces the "Improvements needed" marker for the testing
topic with an initial section of overview information and jumping off links
to sig-testing, test documentation, and test code.

Part of: kubernetes#1413

Signed-off-by: Tim Pepper <tpepper@vmware.com>

tpepper added a commit to tpepper/community that referenced this issue Dec 7, 2017

contributing guide: add initial section on testing
This commit replaces the "Improvements needed" marker for the testing
topic with an initial section of overview information and jumping off links
to sig-testing, test documentation, and test code.

Part of: kubernetes#1413

Signed-off-by: Tim Pepper <tpepper@vmware.com>

k8s-github-robot pushed a commit that referenced this issue Dec 8, 2017

Kubernetes Submit Queue
Merge pull request #1468 from tpepper/contrib_guide
Automatic merge from submit-queue.

contributing guide: add initial section on testing

This commit replaces the "Improvements needed" marker for the testing
topic with an initial section of overview information and jumping off links
to sig-testing, test documentation, and test code.

Part of: #1413

Signed-off-by: Tim Pepper <tpepper@vmware.com>
@idvoretskyi

This comment has been minimized.

Copy link
Member

idvoretskyi commented Dec 14, 2017

@anubhakushwaha

This comment has been minimized.

Copy link

anubhakushwaha commented Dec 14, 2017

@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.

k8s-github-robot pushed a commit that referenced this issue Dec 14, 2017

Kubernetes Submit Queue
Merge pull request #1505 from guineveresaenger/sig
Automatic merge from submit-queue.

Explain SIGs better, note on where to find technical support

This is in partial fulfillment of umbrella issue #1413.

tpepper added a commit to tpepper/community that referenced this issue Dec 14, 2017

contrib guide: add table of contents
We're to a point were seeing the table of contents at the top is
informative about overall flow of the doc.  Will need to regenerate this
if/when new sections are added since it's not a render-time artifact.

Relates to issues kubernetes#1413.

Signed-off-by: Tim Pepper <tpepper@vmware.com>

k8s-github-robot pushed a commit that referenced this issue Dec 14, 2017

Kubernetes Submit Queue
Merge pull request #1507 from tpepper/contrib_guide
Automatic merge from submit-queue.

contrib guide: add table of contents

We're to a point were a table of contents at the top of the contrib guide
is informative on overall flow of the doc.  Will need to regenerate this
if/when new sections are added since it's not a render-time artifact.

Relates to issues #1413.

Signed-off-by: Tim Pepper <tpepper@vmware.com>

@cblecker cblecker reopened this Dec 18, 2017

@guineveresaenger

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Dec 18, 2017

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

@cblecker

This comment has been minimized.

Copy link
Member

cblecker commented Dec 18, 2017

@guineveresaenger already done :)

@guineveresaenger

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Jan 16, 2018

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

@castrojo

This comment has been minimized.

Copy link
Contributor

castrojo commented Jan 22, 2018

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

This comment has been minimized.

Copy link
Contributor

tpepper commented Jan 24, 2018

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.

@tpepper tpepper referenced this issue Jan 25, 2018

Merged

Guide moves #1676

@guineveresaenger

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Jan 26, 2018

@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

This comment has been minimized.

@castrojo

This comment has been minimized.

Copy link
Contributor

castrojo commented Jan 31, 2018

@castrojo

This comment has been minimized.

Copy link
Contributor

castrojo commented Feb 7, 2018

/help

@k8s-ci-robot

This comment has been minimized.

Copy link
Contributor

k8s-ci-robot commented Feb 7, 2018

@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:

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

@tpepper

This comment has been minimized.

Copy link
Contributor

tpepper commented Feb 7, 2018

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

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Feb 7, 2018

@tpepper noted, above

@guineveresaenger

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Feb 8, 2018

@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

This comment has been minimized.

Copy link

ryanj commented Mar 11, 2018

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

@cblecker cblecker added this to Backlog in Contributor Experience via automation May 3, 2018

@cblecker cblecker moved this from Backlog to Tracking/Umbrella Issues in Contributor Experience May 3, 2018

@guineveresaenger

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented May 18, 2018

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

This comment has been minimized.

Copy link
Contributor Author

guineveresaenger commented Aug 2, 2018

As of PR #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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.