diff options
Diffstat (limited to 'mod/mod-ci-github-gq.hxx')
| -rw-r--r-- | mod/mod-ci-github-gq.hxx | 109 |
1 files changed, 60 insertions, 49 deletions
diff --git a/mod/mod-ci-github-gq.hxx b/mod/mod-ci-github-gq.hxx index 439f7b7..50950d4 100644 --- a/mod/mod-ci-github-gq.hxx +++ b/mod/mod-ci-github-gq.hxx @@ -19,24 +19,32 @@ namespace brep // GraphQL functions (all start with gq_). // - // Create a new check run on GitHub for each build. Update `check_runs` with - // the new states and node IDs. Return false and issue diagnostics if the - // request failed. + // Create a new check run on GitHub for each build with the build state, + // name, and details_url taken from each check_run object. Update + // `check_runs` with the new data (node id and state_synced). Return false + // and issue diagnostics if the request failed. // - // Note: no details_url yet since there will be no entry in the build result - // search page until the task starts building. + // Throw invalid_argument if the passed data is invalid, missing, or + // inconsistent. + // + // Note that creating a check_run named `foo` will effectively replace any + // existing check_runs with that name. They will still exist on the GitHub + // servers but GitHub will only consider the latest one (for display in the + // UI or in determining the mergeability of a PR). // bool gq_create_check_runs (const basic_mark& error, vector<check_run>& check_runs, const string& installation_access_token, const string& repository_id, - const string& head_sha, - build_state); + const string& head_sha); // Create a new check run on GitHub for a build. Update `cr` with the new - // state and the node ID. Return false and issue diagnostics if the request - // failed. + // data (node id, state, and state_synced). Return false and issue + // diagnostics if the request failed. + // + // Throw invalid_argument if the passed data is invalid, missing, or + // inconsistent. // // If the details_url is absent GitHub will use the app's homepage. // @@ -61,11 +69,15 @@ namespace brep build_state, optional<gq_built_result> = nullopt); - // Update a check run on GitHub. + // Update a check run on GitHub. Update `cr` with the new data (state and + // state_synced). Return false and issue diagnostics if the request failed. + // + // Throw invalid_argument if the passed data is invalid, missing, or + // inconsistent. // - // Send a GraphQL request that updates an existing check run. Update `cr` - // with the new state. Return false and issue diagnostics if the request - // failed. + // Note that GitHub allows any state transitions except from built (but + // built to built is allowed). The latter case is signalled by setting the + // check_run state_synced member to false and the state member to built. // // If the details_url is absent GitHub will use the app's homepage. // @@ -83,51 +95,50 @@ namespace brep build_state, optional<gq_built_result> = nullopt); - // Fetch a pull request's mergeability from GitHub and return it in first, - // or absent if the merge commit is still being generated. + // Fetch pre-check information for a pull request from GitHub. This + // information is used to decide whether or not to CI the PR and is + // comprised of the PR's head commit SHA, whether its head branch is behind + // its base branch, and its mergeability and test merge commit SHA. // - // Return false in second and issue diagnostics if the request failed. - // - struct gq_pr_mergeability - { - // True if the pull request is auto-mergeable; false if it would create - // conflicts. - // - bool mergeable; - - // The ID of the test merge commit. Empty if mergeable is false. - // - string merge_commit_id; - }; - - - // Fetch a pull request's mergeability from GitHub. Return absent value if - // the merge commit is still being generated. Return empty string if the - // pull request is not auto-mergeable. Otherwise return the test merge - // commit id. + // Return absent value if the merge commit is still being generated (which + // means PR head branch behindness is not yet known either). See the + // gq_pr_pre_check struct's member comments for non-absent return value + // semantics. // // Issue diagnostics and return absent if the request failed (which means it // will be treated by the caller as still being generated). // + // Throw invalid_argument if the node id is invalid. + // // Note that the first request causes GitHub to start preparing the test // merge commit. // - optional<string> - gq_pull_request_mergeable (const basic_mark& error, - const string& installation_access_token, - const string& node_id); - - // Fetch the last 100 open pull requests with the specified base branch from - // the repository with the specified node ID. - // - // Issue diagnostics and return nullopt if the repository was not found or - // an error occurred. + // For details regarding the test merge commit and how to check/poll for PR + // mergeability see + // https://docs.github.com/en/rest/pulls/pulls?#get-a-pull-request and + // https://docs.github.com/en/rest/guides/using-the-rest-api-to-interact-with-your-git-database?#checking-mergeability-of-pull-requests // - optional<vector<gh_pull_request>> - gq_fetch_open_pull_requests (const basic_mark& error, - const string& installation_access_token, - const string& repository_node_id, - const string& base_branch); + struct gq_pr_pre_check_info + { + // The PR head commit id. + // + string head_sha; + + // True if the PR's head branch is behind its base branch. + // + bool behind; + + // The commit id of the test merge commit. Absent if behind or the PR is + // not auto-mergeable. + // + optional<string> merge_commit_sha; + }; + + optional<gq_pr_pre_check_info> + gq_fetch_pull_request_pre_check_info ( + const basic_mark& error, + const string& installation_access_token, + const string& node_id); } #endif // MOD_MOD_CI_GITHUB_GQ_HXX |