Edits and additions to Wiki for GHA `issue-trigger.yml`

[t-will-gillis]

Issue Trigger
_Workflow

Summary

The issue-trigger.yml workflow is triggered whenever an issue trigger (aka event_action) is opened, transferred, assigned, labeled, or unlabeled. Workflow steps run for different triggers: for example, "Add-Missing-Labels-To-Issues" is triggered when an issue is opened or transferred, "Ask-For-Preliminary-Update" when assigned, and "Add-Feature-Branch-Comment" and "Remove-Feature-Branch-Comment" when labeled or unlabeled (and that label is Feature: Feature Branch).

Triggers

• Runs on the "Issue" event when issue is:
  • opened
  • transferred
  • assigned
  • labeled (and label == Feature: Feature Branch)
  • unlabeled (and label == Feature: Feature Branch)

Labels Used by Workflow

• Complexity: Missing (future "complexityMissingLabel" labelKey)
• Complexity: Small (future "complexitySmallLabel" labelKey)
• Complexity: Prework (future "complexityPreworkLabel" labelKey)
• good first issue (future "goodFirstIssueLabel" labelKey)
• size: missing (future "sizeMissingLabel" labelKey)
• size: 0.25pt (future "size025ptLabel" labelKey)
• role missing (future "roleMissingLabel" labelKey)
• role: front end (future "roleFrontEndLabel" labelKey)
• role: back end/devOps (future "roleBackEndDevOpsLabel" labelKey)
• role: design (future "roleDesignLabel" labelKey)
• role: user research (future "roleUserResearchLabel" labelKey)
• role: dev leads (future "roleDevLeadsLabel" labelKey)
• Feature: Missing (future "featureMissingLabel" labelKey)
• Feature: Administrative (future "featureAdminLabel" labelKey)
• ready for dev lead (future "readyForDevLeadLabel" labelKey)
• Draft (future "draftLabel" labelKey)

Tokens Used by Workflow

• TEAMS
• HACKFORLA_GRAPHQL_TOKEN

Workflow Files

• issue-trigger.yml
  • add-missing-labels-to-issues/
  • check-labels.js
  • post-labels-comment.js
    • add-labels-template.md
  • add-preliminary-comment/
  • check-label-preliminary-update.js
  • preliminary-update.comment.js
    • preliminary-update.md
    • multiple-issue-reminder.md
    • draft-label-reminder.md
    • unassign-from-NIA.md
    • post-issue-comment.js (in utils folder)
    • format-comment.js (in utils folder)
    • get-timeline.js (in utils folder)
  • feature-branch-comment/
  • add-feature-branch-comment.js
    • feature-branch-comment.md
    • post-issue-comment.js (in utils folder)
    • format-comment.js (in utils folder)
  • hide-feature-branch-comment.js

Support File Folders:

• .github/workflows
• github-actions/trigger-issue
• github-actions/utils

Process:

• The schedule-monthly.yml workflow is triggered on a cron schedule at 11:00 UTC / 4:00 am PDT on the first day of every month, except January and August. (January and August are omitted because the 'website' team takes off December and July. The time limits discussed below are adjusted to account for this expected inactivity during the break.)
• This workflow consists of the job "Trim_Contributors" and three main steps:
  • "Get Contributors" calls get-contributors-data.js:
  • The function fetchContributors() queries GitHub for data about all user contributions to the 'hackforla/website' repo:
    • If a user made any contribution due to 1. commits, 2. comments, or 3. issue assignments.
    • All user contributions within the last month (first run, allContributorsSinceOneMonthAgo) and within the last two months (second run, allContributorsSinceTwoMonthsAgo) are recorded.
    • Note that members of the 'website-admin' team as well as three Hack for LA bot accounts are considered 'permanent contributors' and are automatically included in these two lists regardless of contributions.
    • This function also records any open issue whose assignee does not show any activity within the last two months, and whether the issue is a "Pre-work Checklist"- inactiveWithOpenIssue.
  • "Trim Inactive Members" calls trim-inactive-members.js:
  • The function readPreviousNotifyList() retrieves the list of 'notified members' from the previous month previouslyNotified.
  • The function getTeamMembers() records all current 'website-write' team members currentTeamMembers.
  • The function removeInactiveMembers() iterates through the list of current team members and checks whether the member is listed on the allContributorsSinceTwoMonthsAgo list. If the team member does not show any activity in the last two months, the function then checks:
    • whether the team member is listed on the 'website' team; if not the person is added. (We want to make sure that the member is on the 'website' team before they are removed from 'website-write' team),
    • whether the team member is on the list of inactiveWithOpenIssue and the issue is not a "Pre-work Checklist", if so their name and issue are added to cannotRemoveYet. (We don't want to remove the person with an open assignment)
    • whether or not the team member was notified of their inactivity in the last month, i.e. whether their name is on the previouslyNotified list. If not, they will not be removed in the current month. (We want to give people a notification prior to removing them from the 'website-write' team)
    • Else, the team member will be removed from both the 'website-write' and 'website-merge' teams if applicable.
    • If the member that was just removed has an open "Pre-work Checklist", this issue is closed by the bot vis closePrework().
  • The function getTeamMembers() then runs a second time to update the list of updatedTeamMembers.
  • The function notifyInactiveMembers() iterates through the list of updated team members and checks whether the member is listed on the allContributorsSinceOneMonthAgo list. If the member does not show any activity within the last month, the function checks:
    • whether the member cloned HfLA's repo within last month. If so, then the member might be new and are still setting up, and they will not be notified of inactivity yet.
    • otherwise, the member is added to the list of members to be notified.
  • "Update Inactive Members JSON" uses stefanzweifel/git-auto-commit-action@v5.0.1 to commit the record of inactive-members.json to the repo.
• The post workflow file wr-schedule-monthly.yml runs if schedule-monthly.yml is successful and includes:
  • The job "Create-New-Issue" and related Step call create-new-issue.js:
  • The function createIssue() writes the lists of removed members and members to be notified to a template inactive-members.md
  • The function postComment() posts a comment to the Monday Dev Meeting Agenda issue informing that the workflow has run, linking to the issue that was created, and if applicable listing members with open issues (and issue number) post-issue-comment.js module module
  • The job "Close-New-Issue" gathers the pertinent data and then as a last step closes the just-generated "Review Inactive Team Members" issue.

Data auto-generated by Google Sheets worksheets (maintained in the "hackforla-bot@hackforla.org" account) complement this workflow:

• Current 'website-write' team
• Current Google Drive (Website) Registrants

Test Procedure

Important note: line numbers and specific code references may have changed slightly since the time of this Wiki- verify with the actual files.

• [ ] You will need to have a functioning test environment on your local repo. Refer to Hack for LA's GitHub Actions, especially Tips 6 & 7.
• [ ] In addition to the 'files changed' in the PR, there are additional changes that you should make to help with testing. If you do not make these edits, you might delete or mis-edit Hack for LA data, delete team members, generate false or junk notifications, and/or create junk issues on HfLA's live project board.
• [ ] In schedule-monthly.yml, you will need to activate two personal tokens.
  • [ ] HACKFORLA_BOT_PA_TOKEN scopes: admin:org_hook, public_repo
  • [ ] HACKFORLA_ADMIN_TOKEN scopes: admin:org_hook, repo, write:org
• [ ] In the same file, around line 12, replace 'hackforla' with your personal repo.
• In get-contributors-data.js
  • [ ] Near line 84 replace with owner: 'hackforla',
  • [ ] Near line 85 replace with repo: 'website', (unless your repo is 'website')

• In 'trim-inactive-members.js`:

  • [ ] IMPORTANT: Disable lines 84-88 by replacing:

    await github.request('DELETE /orgs/{org}/teams/{team_slug}/memberships/{username}', {
        org: context.repo.owner,
        team_slug: team,
        username: username,
      });
    }

    with:

      console.log('Would be removed: ' + username);
      // await github.request('DELETE /orgs/{org}/teams/{team_slug}/memberships/{username}', {
      //   org: context.repo.owner,
      //   team_slug: team,
      //   username: username,
      // });
    }

  • [ ] IMPORTANT: Disable entirely the closePrework() function, starting around ln 110:

    async function closePrework(member, issueNum){ 
    console.log('skipping closePrework()');
    // Close the assignee's "Pre-work Checklist" and add comment
    // await github.request('PATCH /repos/{owner}/{repo}/issues/{issue_number}', {
    //   owner: org,
    //   repo: repo,
    //   issue_number: issueNum,
    //   state: 'closed'
    // });
    // console.log('Closing "Pre-work Checklist" issue number ' + issueNum + ' for ' + member);
    // // Add comment to issue
    // await github.request('POST /repos/{owner}/{repo}/issues/{issue_number}/comments', {
    //   owner: org,
    //   repo: repo,
    //   issue_number: issueNum,
    //   body: 'The Hack for LA Bot has closed this issue due to member inactivity.'
    // });
    }

• In create-new-issue.js:
  • [ ] Ln 20 should be OK as written, but you can replace const owner = '<your name>'; NOT 'hackforla'
  • [ ] Ln 21 should be OK as written, but you can replace const repo = '<your repo name>';
  • [ ] Ln 22, replace with an existing issue number in your repo
  • [ ] IMPORTANT: around lines 38-39 replace with:

    let removedList = removeList.map(x => "@ " + x).join("\n");    // important to add space
    let notifiedList = notifyList.map(x => "@ " + x).join("\n");   // important to add space

  • Comment out ln 58, i.e.: // let milestone = parseInt(issueObject['milestone']);
  • Comment out ln 73, i.e.: // milestone,
• In /utils/get-team-members.js:
  • [ ] Ln 16, replace with org: 'hackforla',
• In /utils/add-team-member.js:
  • [ ] Ln 11, replace with org: 'hackforla',
  • [ ] Ln 18, replace with org: 'hackforla',
• In /utils/get-timeline.js:
  • [ ] Ln 16, replace with owner: 'hackforla',
  • [ ] Ln 17, replace with repo: 'website',
• In /utils/post-issue-comment.js:
  • [ ] Ln 9, replace with owner: ' <your name> ', NOT 'hackforla'
  • [ ] Ln 10, replace with repo: 'website',

Testing Resources

• Hack for LA's GitHub Actions (interim update)
• How to Test GitHub Actions
• Additional Notes for GitHub Actions

[github-actions[bot]]

Hi @t-will-gillis.

Please don't forget to add the proper labels to this issue. Currently, the labels for the following are missing:

• Complexity, Role, Feature, Size

NOTE: Please ignore this comment if you do not have 'write' access to this directory.

To add a label, take a look at Github's documentation here.

Also, don't forget to remove the "missing labels" afterwards. To remove a label, the process is similar to adding a label, but you select a currently added label to remove it.

After the proper labels are added, the merge team will review the issue and add a "Ready for Prioritization" label once it is ready for prioritization.

Additional Resources:

• Wiki: How to create issues
• Wiki: How to read and interpret labels