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

Proposal: move things like API conventions back to k/k or somewhere more logical #7421

Open
thockin opened this issue Jul 26, 2023 · 23 comments
Labels
sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. sig/contributor-experience Categorizes an issue or PR as relevant to SIG Contributor Experience.

Comments

@thockin
Copy link
Member

thockin commented Jul 26, 2023

Describe the issue

There's a discussion in sig-net for where to put docs related to "how to write a service proxy". This is highly technical, and is coupled to core kubernetes APIs. Putting it in k/community/contributors/devel feels wrong.

We have things like the API conventions there, already, and they are hard to find. Yes, API conventions apply to more than just k/k, but k/k feels like a better home, to me.

What if we moved those docs to k/k/docs/dev/.. ?

@liggitt @danwinship @sftim

@k8s-ci-robot k8s-ci-robot added the needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. label Jul 26, 2023
@sftim
Copy link
Contributor

sftim commented Jul 26, 2023

I'd put these conventions within https://k8s.dev/docs/

I don't mind where the source Markdown lives.

@thockin
Copy link
Member Author

thockin commented Jul 26, 2023 via email

@thockin
Copy link
Member Author

thockin commented Jul 26, 2023

The reason I like k/k is that I can update docs and code together :)

@youngnick
Copy link

I would love for the API conventions and API changes docs to be somewhere that's easier to find, I'm constantly sending them to people who are building CRDs.

k8s.dev/docs seems like it would be way better than the current location to me.

@palnabarun
Copy link
Member

/sig architecture
/sig contributor-experience

@k8s-ci-robot k8s-ci-robot added sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. sig/contributor-experience Categorizes an issue or PR as relevant to SIG Contributor Experience. and removed needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. labels Jul 28, 2023
@palnabarun
Copy link
Member

k8s.dev/docs seems like it would be way better than the current location to me.

Wherever the docs live, AFAIK we can link the docs to the contributor-website easily. There is a mechanism to pull in markdown content from other repos.

@mrbobbytables
Copy link
Member

Wherever the docs live, AFAIK we can link the docs to the contributor-website easily. There is a mechanism to pull in markdown content from other repos.

The mechanism is a little jank...its some terrible bash I wrote awhile ago, but somehow still seems to work. As long as the docs follow the style guide, they should render correctly when pulled in by k8s.dev.

The benefit is that it is actually discoverable vs just in GH, but you can still version it and manage it in place alongside k8s

@danwinship
Copy link
Contributor

So...

  1. Everyone agrees it would be good to put more stuff in https://k8s.dev/docs/
  2. We can pull content to there from arbitrary repos, though maybe this process can use some love (and if we're going to pull content from a bunch of places then probably every page should have an explicit link back to its source so people can find it when they need to edit it).
  3. No one has objected to the idea of moving k/community/contributors/devel to k/k/docs/devel... should we do that? Should that wait until after the content has been published to k8s.dev?
  4. Even if we didn't move that (or didn't move it right away) we might still start putting other technical docs in k/k now (eg, the service proxy doc) and publishing them to k8s.dev...?

@mrbobbytables
Copy link
Member

3. No one has objected to the idea of moving k/community/contributors/devel to k/k/docs/devel... should we do that?

k/community/devl has a bit more in it with things that probably don't belong in k/k/docs/devel, but we could move the relevant things there.

Should that wait until after the content has been published to k8s.dev?

The "blocker" for publishing to k8s.dev is doing a small audit to make sure it conforms with the style guide (hugo + the script that pulls in data from other sources is more particular about this stuff than github) and adding the right metadata etc at the top of the doc - here is an example:

---
title: "Coding Conventions"
weight: 8
description: |
This document outlines a collection of guidelines, style suggestions, and tips
for writing code in the different programming languages used throughout the
Kubernetes project.
---

One other thought - This pivots slightly to the idea of storing them alongside k/k - but one option would be to make k8s.dev the singular source of truth for everything.

@thockin
Copy link
Member Author

thockin commented Jan 14, 2024

This fell off the bottom of my email.

On one hand, API conventions and similar things are not REALLY specific to k/k. On the other hand, it seems pretty widely agreed that the current home is hard to find and reference.

I don't object to publishing through k8s.dev, but it would be nice if they were easily readable in plain text, too.

The service-proxy doc seems well appropriate for k/k/docs/ but what sort of structure do we want there?

@sftim
Copy link
Contributor

sftim commented Jan 15, 2024

I don't object to publishing through k8s.dev, but it would be nice if they were easily readable in plain text, too.

Markdown is pretty close, so we can likely find a good compromise.

@k8s-triage-robot
Copy link

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

  • After 90d of inactivity, lifecycle/stale is applied
  • After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
  • After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

  • Mark this issue as fresh with /remove-lifecycle stale
  • Close this issue with /close
  • Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

@k8s-ci-robot k8s-ci-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Apr 14, 2024
@k8s-triage-robot
Copy link

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

  • After 90d of inactivity, lifecycle/stale is applied
  • After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
  • After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

  • Mark this issue as fresh with /remove-lifecycle rotten
  • Close this issue with /close
  • Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

@k8s-ci-robot k8s-ci-robot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels May 14, 2024
@thockin
Copy link
Member Author

thockin commented May 14, 2024

/remove-lifecycle rotten

@k8s-ci-robot k8s-ci-robot removed the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label May 14, 2024
@danwinship
Copy link
Contributor

ok, I filed kubernetes/kubernetes#124872 to try to get this going...

@thockin
Copy link
Member Author

thockin commented May 15, 2024

For those following:

Duplicating some from kubernetes/kubernetes#124872

We need more technical docs and we need to keep them more up to date. IMO, these are not "glossy", end-user facing docs that need fancy formatting. They are (IMO) text docs (or simple markdown), which are aimed at implementors. I'm not AGAINST fancy formatting, but I don't want to waste time on it.

Today the answer for such docs would be either https://git.k8s.io/community/contributors/devel/sig-xyz or https://git.k8s.io/community/sig-xyz - neither is terrible, but really "community" is not the repo wherein I would expect to find technical docs.

So, to me it makes sense to stick them in k/k/docs/..., but I would be fine with something like k/dev-docs/..., and if pressed I could just concede one of the above.

@sftim
Copy link
Contributor

sftim commented May 15, 2024

https://github.com/kubernetes/contributor-site/? “simple Markdown” is fine there; no expectation of following the SIG Docs style guide, of making text localization friendly, etc.

It's also where we should be telling contributors to look: https://k8s.dev/docs/

@sftim
Copy link
Contributor

sftim commented May 15, 2024

If someone wants to do k/k and a Prow job or GitHub Action so that code and docs change together, that's OK. But if we tell people “look at https://k8s.dev/docs/” then that's much easier than “look at https://k8s.dev/docs/, and also here, and also there, and…”.

It needs to be easy, because contributors also have the option of deciding it's not worth the effort to keep looking.

@danwinship
Copy link
Contributor

I thought discussion above (#7421 (comment)) implied that k8s.dev could pull documentation from multiple repos? (Or maybe it implied there was an existing mechanism to sync content from other repos into kubernetes/contributor-site? I guess it wasn't clear...) @palnabarun @mrbobbytables ?

@mrbobbytables
Copy link
Member

I thought discussion above (#7421 (comment)) implied that k8s.dev could pull documentation from multiple repos? (Or maybe it implied there was an existing mechanism to sync content from other repos into kubernetes/contributor-site? I guess it wasn't clear...) @palnabarun @mrbobbytables ?

It can pull from multiple repos, its a bit jank and could use an update (rewrite in something other than bash >_>) but it works. Mostly just need to make sure they have the right header in there.

@k8s-triage-robot
Copy link

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

  • After 90d of inactivity, lifecycle/stale is applied
  • After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
  • After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

  • Mark this issue as fresh with /remove-lifecycle stale
  • Close this issue with /close
  • Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

@k8s-ci-robot k8s-ci-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Aug 14, 2024
@k8s-triage-robot
Copy link

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

  • After 90d of inactivity, lifecycle/stale is applied
  • After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
  • After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

  • Mark this issue as fresh with /remove-lifecycle rotten
  • Close this issue with /close
  • Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

@k8s-ci-robot k8s-ci-robot added lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. and removed lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. labels Sep 13, 2024
@thockin
Copy link
Member Author

thockin commented Sep 14, 2024

/remove-lifecycle rotten

@k8s-ci-robot k8s-ci-robot removed the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label Sep 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. sig/contributor-experience Categorizes an issue or PR as relevant to SIG Contributor Experience.
Projects
None yet
Development

No branches or pull requests

8 participants