55 lines
3.7 KiB
Markdown
55 lines
3.7 KiB
Markdown
|
# Automatically extend awards.csv
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
Whenever a pull request (PR) is merged in the [stacker.news](https://github.com/stackernews/stacker.news) repository, a [GitHub Action](https://docs.github.com/en/actions) is triggered:
|
||
|
|
|
||
|
|
If the merged PR solves an issue with [award tags](https://github.com/stackernews/stacker.news?tab=readme-ov-file#contributing),
|
||
|
|
the amounts due to the PR and issue authors are calculated and corresponding lines are added to the [awards.csv](https://github.com/stackernews/stacker.news/blob/master/awards.csv) file,
|
||
|
|
and a PR is opened for this change.
|
||
|
|
|
||
|
|
## Action
|
||
|
|
|
||
|
|
The action is defined in [.github/workflows/extend-awards.yml](.github/workflows/extend-awards.yml).
|
||
|
|
|
||
|
|
Filters on the event type and parameters ensure the action is [triggered only on merged PRs](https://stackoverflow.com/questions/60710209/trigger-github-actions-only-when-pr-is-merged).
|
||
|
|
|
||
|
|
The primary job consists of several steps:
|
||
|
|
- [checkout](https://github.com/actions/checkout) checks out the repository
|
||
|
|
- [setup-python](https://github.com/actions/setup-python) installs [Python](https://en.wikipedia.org/wiki/Python_(programming_language))
|
||
|
|
- [pip](https://en.wikipedia.org/wiki/Pip_%28package_manager%29) installs the [requests](https://docs.python-requests.org/en/latest/index.html) module
|
||
|
|
- a script (see below) is executed, which appends lines to [awards.csv](awards.csv) if needed
|
||
|
|
- [create-pull-request](https://github.com/peter-evans/create-pull-request) looks for modified files and creates (or updates) a PR
|
||
|
|
|
||
|
|
## Script
|
||
|
|
|
||
|
|
The script is [extend-awards.py](extend-awards.py).
|
||
|
|
|
||
|
|
The script extracts from the [environment](https://en.wikipedia.org/wiki/Environment_variable) an authentication token needed for the [GitHub REST API](https://docs.github.com/en/rest/about-the-rest-api/about-the-rest-api) and the [context](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs) containing the event details including the merged PR (formatted in [JSON](https://en.wikipedia.org/wiki/JSON)).
|
||
|
|
|
||
|
|
In the merged PR's title and body it searches for the first [GitHub issue URL](https://github.com/stackernews/stacker.news/issues/) or any number with a hash symbol (#) prefix, and takes this as the issue being solved by the PR.
|
||
|
|
|
||
|
|
Using the GitHub REST API it fetches the issue and analyzes its tags for difficulty and priority.
|
||
|
|
|
||
|
|
It fetches the issue's timeline and counts the number of reviews completed with status 'changes requested' to calculate the amount reduction.
|
||
|
|
|
||
|
|
It calculates the amounts due to the PR author and the issue author.
|
||
|
|
|
||
|
|
It reads the existing awards.csv file to suppress appending redundant lines (same user, PR, and issue) and fill known receive methods (same user).
|
||
|
|
|
||
|
|
Finally, it appends zero, one, or two lines to the awards.csv file.
|
||
|
|
|
||
|
|
## Diagnostics
|
||
|
|
|
||
|
|
In the GitHub web interface under 'Actions' each invokation of the action can be viewed, including environment and [output and errors](https://en.wikipedia.org/wiki/Standard_streams) of the script. First, the specific invokation is selected, then the job 'if_merged', then the step 'Run python extend-awards.py'. The environment is found by expanding the inner 'Run python extended-awards.py' on the first line.
|
||
|
|
|
||
|
|
The normal output includes details about the issue number found, the amount calculation, or the reason for not appending lines.
|
||
|
|
|
||
|
|
The error output may include a [Python traceback](https://realpython.com/python-traceback/) which helps to explain the error.
|
||
|
|
|
||
|
|
The environment contains in GITHUB_CONTEXT the event details, which may be required to understand the error.
|
||
|
|
|
||
|
|
## Security considerations
|
||
|
|
|
||
|
|
The create-pull-request step requires [workflow permissions](https://github.com/peter-evans/create-pull-request#workflow-permissions).
|