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.

Sign up for GitHub

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

Document run state and result #2556

Merged
merged 3 commits into from
Nov 16, 2023
+8 −0
Merged

Document run state and result #2556

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d28d4bb
Document run `state` and `result`
sj26 Nov 15, 2023
9909bb8
Better words describing run results
sj26 Nov 16, 2023
4959148
Re-add stale as a potential result
sj26 Nov 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions pages/apis/rest_api/analytics/runs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ curl "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{su
"id": "64374307-12ab-4b13-a3f3-6a408f644ea2",
"branch": "main",
"commit_sha": "1c3214fcceb2c14579a2c3c50cd78f1442fd8936",
"state": "finished",
"result": "passed",
"url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_slug/runs/64374307-12ab-4b13-a3f3-6a408f644ea2",
"web_url": "https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_slug/runs/64374307-12ab-4b13-a3f3-6a408f644ea2",
"created_at": "2023-06-25T05:32:53.228Z"
Expand All @@ -36,6 +38,8 @@ curl "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{su
"id": "64374307-12ab-4b13-a3f3-6a408f644ea2",
"branch": "main",
"commit_sha": "1c3214fcceb2c14579a2c3c50cd78f1442fd8936",
"state": "finished",
"result": "passed",
"url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_slug/runs/64374307-12ab-4b13-a3f3-6a408f644ea2",
"web_url": "https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_slug/runs/64374307-12ab-4b13-a3f3-6a408f644ea2",
"created_at": "2023-06-25T05:32:53.228Z"
Expand All @@ -45,3 +49,7 @@ curl "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{su
Required scope: `read_suites`

Success response: `200 OK`

Runs are created with a `state` of `running` and proceed to `finished` when all uploads have been processed. The run may return to `running` if additional results are uploaded.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Runs are created with a `state` of `running` and proceed to `finished` when all uploads have been processed. The run may return to `running` if additional results are uploaded.
Runs are created with a `state` of `running` and proceed to `finished` when all uploads have been processed. The run may return to `running` if additional results are uploaded. If a run receives no results within a reasonable time period its `state` will proceed to `stale`.

Copy link
Contributor

Choose a reason for hiding this comment

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

FYI our default scope on runs excludes runs that are stale, so I think the behaviour might be that the API will returning the running run if requested, but once the run becomes stale the same API request will probably return a not found or similar?

Copy link
Contributor

Choose a reason for hiding this comment

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

This would happen now with the API as well so I'm not suggesting a change in behaviour, I was just wondering maybe if we shouldn't mention the stale state at all because it wouldn't ever be returned to the customer in the API

Copy link
Member Author

@sj26 sj26 Nov 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

I don't think this addition here is correct. result can become stale, but state can only be running or finished.

https://github.com/buildkite/buildkite/blob/59f40cc5f38003926cb6a91945a923ac12af4860/app/models/analytics/run.rb#L13-L23

I've re-added the words to the state paragraph.

But point taken about the default scopes. The docs are pretty light here, so I think a general note about the expected values and transitions is enough.

Copy link
Contributor

Choose a reason for hiding this comment

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

Oh, I totally thought stale was a state and not a result, but yeah that's not what the code says!


`result` starts as `pending` and may proceed to `passed` or `failed` once finished. If a run does not complete within a reasonable time period it may also proceed to `stale`. `result` may change back to `pending` or change between `passed` and `failed` if additional results are uploaded.
sj26 marked this conversation as resolved.
Show resolved Hide resolved