Skip to content

Add guidance on API documentation - #4160

Merged
k8s-ci-robot merged 5 commits into
kubernetes-sigs:mainfrom
rikatz:gep-4012-improve-godoc
May 20, 2026
Merged

k8s-ci-robot merged 5 commits into
kubernetes-sigs:mainfrom
rikatz:gep-4012-improve-godoc

Conversation

@rikatz

@rikatz rikatz commented Oct 9, 2025

Copy link
Copy Markdown
Member

What type of PR is this?
/kind gep
/kind documentation

What this PR does / why we need it:
This PR adds the memorandum GEP on how implementor should be writing API documentation, in a way to reduce the CRD size, the burden on Gateway API users and still provide meaningful information for other developers

Which issue(s) this PR fixes:
Fixes #4012

Does this PR introduce a user-facing change?:

NONE

@k8s-ci-robot k8s-ci-robot added kind/gep PRs related to Gateway Enhancement Proposal(GEP) release-note-none Denotes a PR that doesn't merit a release note. kind/documentation Categorizes issue or PR as related to documentation. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Oct 9, 2025
@k8s-ci-robot k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Oct 9, 2025
@rikatz
rikatz force-pushed the gep-4012-improve-godoc branch from b9cd854 to e18fedd Compare October 9, 2025 20:15
@rikatz

rikatz commented Oct 9, 2025

Copy link
Copy Markdown
Member Author

/cc @kflynn @candita @Miciah @shaneutt

@k8s-ci-robot

Copy link
Copy Markdown
Contributor

@rikatz: GitHub didn't allow me to request PR reviews from the following users: Miciah.

Note that only kubernetes-sigs members and repo collaborators can review this PR, and authors cannot review their own PRs.

Details

In response to this:

/cc @kflynn @candita @Miciah @shaneutt

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-sigs/prow repository.

@rikatz

rikatz commented Oct 9, 2025

Copy link
Copy Markdown
Member Author

and
/cc @youngnick

@k8s-ci-robot
k8s-ci-robot requested a review from youngnick October 9, 2025 20:16
@rikatz
rikatz force-pushed the gep-4012-improve-godoc branch from e18fedd to bff7eb9 Compare October 9, 2025 20:17
Comment thread geps/gep-4012/index.md Resolved
@rikatz
rikatz force-pushed the gep-4012-improve-godoc branch from bff7eb9 to 98f4d40 Compare November 7, 2025 18:27
@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 7, 2025
@rikatz

rikatz commented Nov 7, 2025

Copy link
Copy Markdown
Member Author

/approve cancel
Not fun if I approve my own stuff ;)

@shaneutt @robscott let me know if this is better

@k8s-ci-robot k8s-ci-robot removed the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Nov 7, 2025
@rikatz
rikatz force-pushed the gep-4012-improve-godoc branch from 98f4d40 to 0186976 Compare November 7, 2025 18:34

@youngnick youngnick left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some native-speaker suggestions for tidying up the English. English sucks.

Comment thread site-src/contributing/devguide.md Resolved
Comment thread site-src/contributing/devguide.md Resolved
Comment thread site-src/contributing/devguide.md Resolved
Comment thread site-src/contributing/devguide.md Resolved
@rikatz

rikatz commented Dec 5, 2025

Copy link
Copy Markdown
Member Author

thanks @youngnick ! Commited your suggestions here!

@k8s-triage-robot

Copy link
Copy Markdown

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

This bot triages PRs 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 PR is closed

You can:

  • Mark this PR as fresh with /remove-lifecycle stale
  • Close this PR 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 Mar 5, 2026
@rikatz

rikatz commented Mar 5, 2026

Copy link
Copy Markdown
Member Author

/remove-lifecycle stale

@k8s-ci-robot k8s-ci-robot removed the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Mar 5, 2026
@rikatz rikatz changed the title GEP-4012 - Godoc improvements Add guidance on API documentation Apr 30, 2026
Comment thread site-src/contributing/devguide.md Resolved
Comment thread site-src/contributing/devguide.md Resolved
Comment thread site-src/contributing/devguide.md Resolved
Comment thread site-src/contributing/devguide.md Resolved
@rikatz
rikatz force-pushed the gep-4012-improve-godoc branch from 7a8aef5 to f67a62b Compare May 18, 2026 21:12
* What is the main feature of the API and Field - Eg.: "`foo` allows configuring how a
a header should be forwarded to backends"
* What is the support level of the field - Eg.: "Support: Core/Extended/Implementation Specific"
* Caveats of that field - Eg.: "Setting `goo` field can have conflicts with `bar` field, and in this

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Caveats of that field - Eg.: "Setting `goo` field can have conflicts with `bar` field, and in this
* Caveats of that field - Eg.: "Setting `foo` field can have conflicts with `bar` field, and in this

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated on my last commit

@kflynn

kflynn commented May 20, 2026

Copy link
Copy Markdown
Contributor

@rikatz Thanks for sticking with this! I make one suggested edit to fix what looks like a typo, but I think we should land this. 🙂

@kflynn

kflynn commented May 20, 2026

Copy link
Copy Markdown
Contributor

👍

/lgtm
/approve
/unhold

@k8s-ci-robot k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label May 20, 2026
@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 20, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kflynn

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 20, 2026
@rikatz

rikatz commented May 20, 2026

Copy link
Copy Markdown
Member Author

/hold

@k8s-ci-robot k8s-ci-robot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. and removed lgtm "Looks good to me", indicates that a PR is ready to be merged. labels May 20, 2026
@rikatz
rikatz force-pushed the gep-4012-improve-godoc branch from 1507301 to 18bb130 Compare May 20, 2026 18:59
@rikatz

rikatz commented May 20, 2026

Copy link
Copy Markdown
Member Author

/hold cancel

@k8s-ci-robot k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label May 20, 2026
@bexxmodd

Copy link
Copy Markdown
Contributor

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 20, 2026
@kflynn

kflynn commented May 20, 2026

Copy link
Copy Markdown
Contributor

/lgtm

@k8s-ci-robot
k8s-ci-robot merged commit c01b9ff into kubernetes-sigs:main May 20, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/documentation Categorizes issue or PR as related to documentation. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note-none Denotes a PR that doesn't merit a release note. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

GEP: Improve godoc/CRD readability