Skip to content

Add owner and parent fields clarification to docs #35023

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

AlexMaryW
Copy link
Contributor

Issue: #9637

Changes introduced: I have clarified the problematic terms (owner and parent) in all affected endpoints.

The changes were made to relevant:

  • HTTP endpoint parameters' descriptions
  • response/request models' fields

This MR is big, but most changes are the same. If you'd like me to break this MR into several smaller ones, let me know :)

@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Jul 9, 2025
@github-actions github-actions bot added modifies/api This PR adds API routes or modifies them modifies/go Pull requests that update Go code labels Jul 9, 2025
@AlexMaryW AlexMaryW force-pushed the add-owner-parent-docs branch 2 times, most recently from 211731c to 0dec2d1 Compare July 9, 2025 19:09
Copy link
Member

@techknowlogick techknowlogick left a comment

Choose a reason for hiding this comment

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

Amazing, thanks!

@GiteaBot GiteaBot added lgtm/need 1 This PR needs approval from one additional maintainer to be merged. and removed lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. labels Jul 9, 2025
@silverwind silverwind added the type/docs This PR mainly updates/creates documentation label Jul 10, 2025
@wxiaoguang
Copy link
Contributor

Most changes are:

- //   description: owner of the repo
+ //   description: username of the user or organization owning the repository

IMO "owner" is already a widely used concept, we can explain it somewhere, and keep the old description. Old description looks clearer

@wxiaoguang wxiaoguang marked this pull request as draft July 11, 2025 03:22
@AlexMaryW AlexMaryW force-pushed the add-owner-parent-docs branch from 714fcc9 to 7eb36d8 Compare July 13, 2025 10:41
@AlexMaryW
Copy link
Contributor Author

Most changes are:

- //   description: owner of the repo
+ //   description: username of the user or organization owning the repository

IMO "owner" is already a widely used concept, we can explain it somewhere, and keep the old description. Old description looks clearer

Thanks for reviewing the MR! :)

  • A new Gitea user might not be familiar with the owner concept and then the old description sounds confusing (as flagged in this issue).
  • It's considered good practice to think of API docs as reference material. Hence, we should provide all necessary information in every single endpoint instead of explaining all concepts only once or assuming prior knowledge.
  • The owner definition in the regular Gitea docs (the only definition I could find) does not match the API definition of the owner. For example, the regular docs state that a user or several of them can be owners of the repo and it is true of the Gitea UI. On the other hand, the API does not allow for many users to own a repo; it can either be a user or an org and the API considers both as the same object. If someone new to the concept reads the regular docs and then goes on to use the API, their understanding of owner will not be correct.
  • If the definitions of owner for UI and API differ, we cannot explain the concept in the regular docs and must use the API docs. From my point of view, there isn't a better place to define this concept than in every affected endpoint. How else can we ensure that the definition is easy to find and that every user will have the correct understanding of the concept?

@AlexMaryW AlexMaryW force-pushed the add-owner-parent-docs branch from 7eb36d8 to 04fde05 Compare July 14, 2025 16:16
@AlexMaryW AlexMaryW marked this pull request as ready for review July 15, 2025 18:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
lgtm/need 1 This PR needs approval from one additional maintainer to be merged. modifies/api This PR adds API routes or modifies them modifies/go Pull requests that update Go code type/docs This PR mainly updates/creates documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants