stacker.news/docs/dev/extend-awards.md

Automatically extend awards.csv

Overview

Whenever a pull request (PR) is merged in the stacker.news repository, a GitHub Action is triggered:

If the merged PR solves an issue with award tags, the amounts due to the PR and issue authors are calculated and corresponding lines are added to the awards.csv file, and a PR is opened for this change.

Action

The action is defined in .github/workflows/extend-awards.yml.

Filters on the event type and parameters ensure the action is triggered only on merged PRs.

The primary job consists of several steps:

• checkout checks out the repository
• setup-python installs Python
• pip installs the requests module
• a script (see below) is executed, which appends lines to awards.csv if needed
• create-pull-request looks for modified files and creates (or updates) a PR

Branch Existence Check

The workflow includes functionality to check if the branch extend-awards/patch already exists. This ensures that if a PR is already open for extending awards.csv, the workflow will add a commit to the existing branch instead of creating a new PR. The steps are as follows:

1. Check if the branch exists:

   • The workflow fetches the branch extend-awards/patch from the remote repository.
   • If the branch exists, an environment variable exists=true is set; otherwise, exists=false.

2. Handle existing branch:

   • If the branch exists (exists=true), the workflow checks out the branch, configures the Github bot user, and commits the changes directly to the branch.
   • If the branch does not exist (exists=false), the workflow creates a new branch and opens a new PR using the create-pull-request action.

This ensures that changes are consolidated into a single PR when possible.

Script

The script is extend-awards.py.

The script extracts from the environment an authentication token needed for the GitHub REST API and the context containing the event details including the merged PR (formatted in JSON).

In the merged PR's title and body it searches for the first GitHub issue URL 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 invocation of the action can be viewed, including environment and output and errors of the script. First, the specific invocation 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 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.