PROCESS CHANGE: Guidance for improved repo structure + centralize/update common files

[carlisia]

Collaborators: @nainaz @aslom

Initial doc for this effort: [PUBLIC] Improve Knative Docs for New Contributors - Google Docs

Related: https://github.com/knative/docs/issues/4538. How is this issue different? This issue proposes pretty much only a restructuring and pruning of what we already have. @aslom's issue proposes an extension to the contributor documentation, to make it more inclusive of many missing instructions one needs to know to be successful contributing to Knative. We are in need of both.

Note: This proposal applies to both Knative and Knative Sandbox GitHub organizations.

Expected benefits. Who gains the benefits? Why will they benefit?

The overarching goal of this effort is to improve our documentation content and discoverability for both contributors and users.

How:

• add/delete/reorg GitHub health files so we can extract the most benefit by using them as intended

• create a new document under the community/mechanics directory that will contain guidance for structuring files/directories and content in all new and existing repos so that they:

  • don't duplicate GH community health files
  • contain a license file for that repo (so ppl who fork it will also fork the license)
  • have a uniform-ish structure
  • are without information that is outdated
  • are without documentation nested in hard to find places
  • point to a main location for the common contributing documentation (namely, this page: https://github.com/knative/community/blob/main/CONTRIBUTING.md)

  This document will also be a good place to add guidance for: handling exceptions to the above, following best practices common for repositories such as having documentation for aspects unique to the repo (setup, tests, etc), having docs.go for godoc related to packages wherever it is applicable (thanks anonymous!), and other similarly useful information.

  ❗Note: This document could:

  a) merge with community/CREATING-A-SANDBOX-REPO.md at main · knative/community, in which case I'd suggest naming it more generically, like Creating a repo, and have a section for sandbox specific instructions, or

  b) be a complement to the above, in which case I suggest transferring this section into this new doc since it covers the same type of content and it is (it seems to me) applicable to all repos, not just the knative-sandbox ones.

  Either way, the section Process (to be executed by TOC or Steering member) - subsection # 2 needs editing.

Why:

• make information and documentation easy to discover not only by browsing directories but also via GH pages such as Issues, Pull Requests, etc.
• eliminate duplication of files across repos when we can avoid it (ie the GitHub health files should only exist in the org's .github repo, except for the rare cases when it makes sense to override them (ex: the spec repo); aka write once, share everywhere
• consistency

Maintainers will benefit by:

• having this explicit guidance, which currently is lacking
• not having to create duplicate GH health files, nor keep them up to date
• enabling users to be more autonomous in resolving their issues by accessing support and other information that is easily maintained in one central location

Contributors and maintainers will benefit by:

• having a higher chance of finding contributing information that is consistent across the organization, that is relevant, and that is also up to date, all the while also having contributing information that is specific to a project
• having a higher chance of finding information 🤓

Users will benefit by:

• having obvious and contextual clues for accessing up-to-date information about their needs, be it support, security vulnerability, CoC, or license

Expected costs. Who bears the costs? How heavy are they?

No cost for new repos, since every repo needs to add documentation. If anything it will be less costly since some documentation will be centralized.

There is a cost for existing repos of reorganizing their repo structure and content to match the new guidance if they want to be up to date with that. But it should be no more than 1 hour of work per repo.

Timeframe for implementation / rollout.

2 weeks

Are you willing to drive the process, or is this a request for help?

Yes, we are a motivated team!

Tasks to mark this effort complete

• [ ] update the Knative Sandbox .github repo so the health files are up to date and contain useful content

  • [x] https://github.com/knative-sandbox/.github/issues/176
  • [ ] delete the license.md file from the .github repo - why:

    You cannot create a default license file. License files must be added to individual repositories so the file will be included when a project is cloned, packaged, or downloaded. - source GH docs

  • [ ] add a code-of-conduct.md file with the latest (version 2.1) of the Covenant Code of Conduct. As an example of how hard it is to give priority to maintaining these files, the community repo is using version 1.4.
  • [ ] add info to these pages that are common and useful to most projects; more can be added/edited later. Projects can override this file in their repo
    • support.md
    • contributing.md

• [ ] update the knative/community: Knative governance and community material. repo after the above gets merged to remove now redundant GH health files as well as the files related to security.

• [ ] edit the the section Process (to be executed by TOC or Steering member) - subsection # 2 in the CREATING-A-SANDBOX-REPO.md document to reflect the changes on the first bullet on this list.

• [ ] create a new document under the community/mechanics and add guidance for structure and content of repositories (link to/from or merge with community/CREATING-A-SANDBOX-REPO.md at main · knative/community · GitHub).

• [ ] Investigate what development related documentation is common across all repos and is missing from the contributor documentation in knative/community: Knative governance and community material., and add it. ko is an example.

PS: wip, I will create issues for these tasks and link them here.

[carlisia]

/assign @evankanderson

[evankanderson]

Happy to review/approve PRs; I'd suggest reordering the first and second items so we have a clear declared state, and then we anneal the actual repo states towards the desired state.

[aslom]

@carlisia @evankanderson @nainaz let start with one project to see how those change work when applied? I can propose to start with one of eventing github projects after asking eventing WG? Added to WG agenda for today (Feb 23) https://docs.google.com/document/d/1Xha-FeunojN49OJN7W0WBnPMcRtp1ycYpbkiir6XsE0/edit#heading=h.8fifh6nkqjbs

[nainaz]

Thank you @Carlisia Thompson @.***> . I think some of these tasks are generic and may need to happen first , but other than that yes, linking to common contributions guide etc can be started with one project at a time. Thank you, -N

On Wed, 23 Feb 2022 at 11:49, Aleksander Slominski @.***> wrote:

@carlisia https://github.com/carlisia @evankanderson https://github.com/evankanderson @nainaz https://github.com/nainaz let start with one project to see how those change work when applied? I can propose to start with one of eventing github projects after asking eventing WG?

— Reply to this email directly, view it on GitHub https://github.com/knative/community/issues/925#issuecomment-1048987754, or unsubscribe https://github.com/notifications/unsubscribe-auth/AISZCFEDI3LHPRSILUP3WCTU4UFXXANCNFSM5OFA7DSQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

You are receiving this because you were mentioned.Message ID: @.***>

[aliok]

Is this still relevant?

[dprotaso]

@knative/technical-oversight-committee will review this issue and discuss it's relevance next TOC meeting

[psschwei]

FWIW I tried adding the COC to the automation a couple of years ago, but we ran into some issues around different repos needing different versions (relevant discussion can be found in https://github.com/knative-extensions/knobots/pull/118). These also aren't the kind of things that change all that often, so we'd need to ask is it worth the time to automate

[dprotaso]

2 cents

• TOC can own the refactoring of .github files (see: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file)
• Given the website redux - can see if other issues that are surfaced here can be reviewed by UX working group
• This issue covers a lot and we should probably split it up

[dprotaso]

Talking to @Cali0707 - UX working group will look into this general problem as part of their Contributor Experience Study - see: https://github.com/knative/ux/issues/98