-
Notifications
You must be signed in to change notification settings - Fork 59.4k
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
More consise Status Check Guide needed for most common use case #33436
Comments
Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines. |
the HowTO should be ideally linked to on the settings page |
@tomsit-ionos Thank you for opening an issue! I'll get this triaged for review ✨ |
This comment was marked as spam.
This comment was marked as spam.
@tomsit-ionos - thank you for your patience waiting for a response to this issue ✨ Many thanks for taking the time to write a detailed description of the problem you encountered and suggestions for how to address it. Your thoughtfulness is much appreciated. I've taken a look at the article you mentioned and a few related ones, and have some suggestions on how someone could make some simple updates to help users learn how status checks work. Outline content plan
How to find the workflow that corresponds to a status check
The names for status checks shown on a pull request are formed as follows:
Examples:
|
Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks
What part(s) of the article would you like to see updated?
I'd love make a contribution via PR but i'm afraid this is beyond my time capacity!
Part 1 Howto Simple Use Case
After running into problems to to config required checks for PRs, i think i understood now how it works -- but only after piecing together the info points spread over several articles, discussions (thank u https://github.com/orgs/community/discussions/26698#discussioncomment-3252954). It would be great to have a simple HowTo for the most common scenario which IMO is: "I have 1..n jobs that need to be OK before the PR can get merged"
The howto is then thus:
jobs.<job-id>.name
(does this default tojobs.<job-id>
?)My Gotcha:
The name of the check is not the same string that is shown on the PR UI, e.g.
It took me a while to get this even after reading the discussion linked above.
I'm guessing the UI string depends how the Job was actually run (nested/triggered by other WFs !? plz expand), e.g. in my case i have 2 jobs in the same WF named
ci
, which is the reason this is indicated by the leadingci/
. However, this must not be added to the name of the status check added in step (4), nor the(push)
suffix which probably indicates the triggering event.The above will probably help more simpletons like me to get things done w/o having to read thru lots of docs.
Part 2 Expand on the Simple Use Case to lead into the more general impl and additional use case of the API
The following is under the assumption that i deducted the following, w/o really delving into the API docs. Reading those might have made things clearer, but i also guess, that a user that just wants to use GH thru web UI and git CLI like me and wants to config the most common use case, is not going to read it either, if not explicitly asked to do so. So let's lower the bar for this!
Something along these lines should be written up concisely in the docs -- starting with the most simple use case that every1 understands and then expand to the general mechanism that Apps and external apps can use but that is also used by the actions themselves, ie a TLDR and its Long Story.
My guess is, that this requires some restructuring of the pages/texts to really make it shine and be easily understandable -- just my 2cts.
Additional information
PS: HUBBERS!! This is the github/docs open source repo. You may want to open an issue in the internal-only github/docs-content repo instead.
i dont understand who u are addressing with the bolded text. Are HUBBERS GH employes that have access to the github/docs-content repo ? -- because i dont. I initially thought that HUBBERS are all github users....
Addition by a GitHub docs team member
Outline content plan
name
for the job or, when no job name is defined, the job identifier. For example, the required status check defined for the content-lint-markdown.yml file islint-content
(no name defined). The required status checks from the test.yml file are the matrix-definednames
.How to find the workflow that corresponds to a status check
The names for status checks shown on a pull request are formed as follows:
name
/
jobname
(trigger)
name
may be defined by a matrix.name
is not defined, theid
is used (see Setting an ID for a job and Setting a name for a job)Examples:
OS Ready for review / Request a review from the docs-content team (pull_request_target)
Test / assets (pull requests)
whereassets
is part of a matrix.The text was updated successfully, but these errors were encountered: