[Schema Inaccuracy] Wordy Plan availability prefix in branch protection endpoint descriptions
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 48/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- openapi
- Domain
- api, documentation
Research direction
Search the OpenAPI descriptions for the /repos/{owner}/{repo}/branches/{branch}/protection operations and the repeated plan-availability sentence. Review how the 34 descriptions are structured, then determine the agreed placement or reuse for that information. Done when each endpoint’s functional description is prominent and the availability wording is no longer unnecessarily repeated.
Written by the indexing model from the issue text.
Description
Schema Inaccuracy
I’ve noticed that the documentation for the /repos/{owner}/{repo}/branches/{branch}/protection endpoints is a bit difficult to read. Currently, 34 different descriptions begin with a boilerplate sentence regarding plan availability:
"Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server."
The actual functional description of the endpoint is buried after this paragraph, which makes it hard to quickly understand what each specific operation does when browsing the spec.
Expected
The documentation could emhpasize the functional description of the endpoint. If the plan availability information is necessary, it would be much more readable if it were:
- Moved to the end of the description.
- Included as a "Note" or metadata field.
- Defined once at the top-level "Branch Protection" category rather than repeated for every sub-operation.
- Dominant language
- No language data
- Stars
- 1.6k
- Forks
- 342
- Avg merge
- 2h 23m
- Merged PRs (30d)
- 57
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/rest-api-description
-
feature
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
github/rest-api-description#7220 ·
-
feature
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
github/rest-api-description#7201 ·
-
feature
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
github/rest-api-description#7163 ·
-
feature
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
github/rest-api-description#7162 ·
-
feature
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
github/rest-api-description#7135 ·
All issues in github/rest-api-description
Similar issues
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
canonical/paas-charm#368 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
tech debt
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
area:workflow bug ready-for-agent
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
fil-donadoni/tolaria#4409 ·
-
status/awaiting_triage
Difficulty 2/5 1-3 hours Newbie friendliness 75/100