Title: Automated Management of Parent-Child Issue Relationships in GitHub Projects
Version: 1.0
Author: Tamir Halperin
Date: Friday, August 23rd, 2024
This specification outlines the implementation of a GitHub Action designed to manage the relationship between "parent" and "child" issues within a GitHub repository. The system will dynamically update parent issues with a list of the top 5 busiest child issues based on the number of comments. It supports multiple parent issues referenced by a single child issue and ensures the parent issue description remains clean and up-to-date.
The purpose of this GitHub Action is to automate the maintenance of parent-child issue relationships by:
- Updating parent issues with the top 5 busiest child issues based on comment activity.
- Handling multiple parent issues referenced in a comma-separated list within a child issue.
- Ensuring that the content in the parent issue description is dynamically replaced, preventing clutter and outdated information.
The action will:
- Be triggered whenever a comment is added to any issue in the repository.
- Detect if the commented issue is a child issue by searching for a "Parents" descriptor in its description.
- Update the descriptions of the referenced parent issues with a dynamically generated list of the top 5 busiest child issues.
- Insert this information into the parent issue description using delimiters to ensure the content is neatly replaced with each update.
A child issue identifies its parent issues through a "Parents" descriptor in the issue description. The format should be:
Parents: #123, #456, #789
Where #123, #456, and #789 are the issue numbers of the parent issues. The action will parse this comma-separated list and handle each parent individually.
The parent issue's description will include a block that displays the top 5 busiest child issues. This block will be enclosed by the following delimiters:
<!-- TOP_5_CHILD_ISSUES_START -->
<!-- TOP_5_CHILD_ISSUES_END -->When the action runs, it will:
- Check if these delimiters exist in the parent issue description.
- If they do, the content between them will be replaced.
- If they don’t, the block will be added at the end of the description.
- The block will be replaced or added only when relevant child issues are identified.
- GitHub Actions: Automates the workflow.
- GitHub CLI (
gh): Used within the action to interact with GitHub’s API. - Shell Scripting: Processes and formats the data within the GitHub Action.
jq: A command-line JSON processor to parse and manipulate JSON data.
Here is the GitHub Action YAML configuration:
name: Update Parent Issues on Comment
on:
issue_comment:
types: [created]
jobs:
update-parent-issues:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v2
- name: Find Parent Issue References
id: find_parents
run: |
PARENTS=$(gh issue view ${{ github.event.issue.number }} --json body --jq '.body | scan("Parents: #([0-9, ]+)") | .[0]')
PARENT_ISSUE_NUMBERS=$(echo $PARENTS | tr ',' '\n' | tr -d ' ')
echo "parent_issue_numbers=$PARENT_ISSUE_NUMBERS" >> $GITHUB_ENV
- name: Get Top 5 Busiest Child Issues and Update Parents
if: env.parent_issue_numbers != ''
run: |
for PARENT in ${{ env.parent_issue_numbers }}; do
CHILD_ISSUES=$(gh issue list --json number,comments,title,html_url --search "Parents: #$PARENT" --jq 'sort_by(.comments) | reverse | .[:5]')
TOP_ISSUES=$(echo "$CHILD_ISSUES" | jq -r '.[] | "- [#" + (.number|tostring) + "](" + .html_url + ") - " + .title + " (" + (.comments|tostring) + " comments)"')
# Fetch the current description of the parent issue
DESCRIPTION=$(gh issue view $PARENT --json body --jq '.body')
# Check if the delimiters exist
if echo "$DESCRIPTION" | grep -q "<!-- TOP_5_CHILD_ISSUES_START -->"; then
# Replace the existing block between delimiters
UPDATED_DESCRIPTION=$(echo "$DESCRIPTION" | sed -e "/<!-- TOP_5_CHILD_ISSUES_START -->/,/<!-- TOP_5_CHILD_ISSUES_END -->/c\\## Top 5 Busiest Child Issues\n<!-- TOP_5_CHILD_ISSUES_START -->\n$TOP_ISSUES\n<!-- TOP_5_CHILD_ISSUES_END -->")
else
# Append the new block if the delimiters do not exist
UPDATED_DESCRIPTION="$DESCRIPTION\n\n## Top 5 Busiest Child Issues\n<!-- TOP_5_CHILD_ISSUES_START -->\n$TOP_ISSUES\n<!-- TOP_5_CHILD_ISSUES_END -->"
fi
# Update the parent issue description
gh issue edit $PARENT --body "$UPDATED_DESCRIPTION"
doneThis GitHub Action is designed to automate the process of maintaining up-to-date information in parent issues about their busiest child issues. By monitoring comments on issues and dynamically updating the descriptions of parent issues, this solution ensures that project management within GitHub remains organized and informative.
The action handles multiple parent issues through a comma-separated list in the child issue's description, updating each parent with relevant child issue activity. The use of delimiters ensures that the top 5 busiest child issues are cleanly and efficiently managed within the parent issue descriptions, preventing clutter and ensuring relevance.
- Add the above YAML code to a
.github/workflowsdirectory in your repository. - Ensure that the
ghCLI tool is properly configured and authenticated within your GitHub Actions environment. - Make sure to communicate the "Parents" descriptor format to all contributors to ensure consistent and accurate tracking of parent-child relationships.
This specification should provide a comprehensive guide for your development team to implement and deploy the described GitHub Action successfully.