Create new Wiki / edit existing Wiki for GHA schedule-monthly.yml and wr-schedule-monthly.yml

[t-will-gillis]

Dependency

• Edits to contributors-data.js and schedule-monthly.yml #6193

Overview

Our Wiki pages need to have accurate and complete information to explain the GitHub Actions that the website uses. Therefore, we need to correct erroneous info and provide new documentation for the GHA schedule-monthly.yml.

Action Items

• Refer to Epic: Update GitHub Action Wiki pages' spreadsheet #4819 and the template illustrated in Update template for HfLA GitHub Actions wiki pages #4841
• DRAFT Make sure summary HfLA GitHub Actions page is referring to correct info-
  • Name is not "update team members", it is now schedule-monthly.yml.
  • The link needs to be updated OR completely replaced
• Needs the page link describing the schedule-monthly.yml. SEE BELOW
• Needs the page for the support wr-schedule-monthly.yml SEE BELOW

UPDATE: See comments below

Resources/Instructions

• This issue is part of the epic to update the GHA Wikis, Epic: Update GitHub Action Wiki pages' spreadsheet #4819
• This issue also addresses remaining items noted in ER ER: Inactive Members, Add'l Revs to GHAs "Schedule Thursday 1100" and "Schedule Monthly" #5163 so that that issue may be closed.

[ExperimentsInHonesty]

@t-will-gillis are you still working on this draft? If you are please assign this to yourself

[github-actions]

Hi @t-will-gillis, thank you for taking up this issue! Hfla appreciates you :)

Do let fellow developers know about your:-
i. Availability: (When are you available to work on the issue/answer questions other programmers might have about your issue?)
ii. ETA: (When do you expect this issue to be completed?)

You're awesome!

P.S. - You may not take up another issue until this issue gets merged (or closed). Thanks again :)

[t-will-gillis]

Schedule Monthly &
WR Schedule Monthly
_Workflows

Summary

The schedule-monthly.yml and wr-schedule-monthly.yml workflows together are intended to monitor the individual activities of each member of the 'website-write' team. Members that have been inactive (as described below) for over two months are removed from the 'website-write' team. Members that have been inactive for over one month (and shy of two months) are notified that the bot will remove their team membership in the next month if the member does not resume activity. Specific details and functionalities are described below.

Trigger

• Workflow runs at 11:00 UTC/ 4:00 PDT, on the 1st day of every month (except January and August)

Labels Used by Workflow

• Complexity: Small (future "complexitySmallLabel" labelKey)
• size: 0.5pt (future "size05ptLabel" labelKey)
• role: dev leads (future "roleDevLeadsLabel" labelKey)
• Feature: Administrative (future "featureAdminLabel" labelKey)
• Feature: Onboarding/Contributing.md (future "featureOnboardContribMdLabel" labelKey)

Tokens Used by Workflow

• HACKFORLA_ADMIN_TOKEN ( used in schedule-monthly.yml )
• HACKFORLA_BOT_PA_TOKEN ( used in wr-schedule-monthly.yml )

Workflow Files

• schedule-monthly.yml
  • get-contributors-data.js (in list-inactive-members folder)
    • get-timeline.js (in utils folder)
    • get-team-members.js (in utils folder)
  • trim-inactive-members.js (in list-inactive-members folder)
    • get-team-members.js (in utils folder)
    • add-team-member.js (in utils folder)
    • inactive-members.json (in utils/data folder)
• wr-schedule-monthly.yml
  • create-new-issue.js (in list-inactive-members folder)
    • issue-template-parser.js (in utils folder)
    • inactive-members.md (in list-inactive-members folder)
    • post-issue-comment.js (in utils folder)

Support File Folders:

• .github/workflows
• github-actions/trigger-schedule/list-inactive-members
• 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 #2607, 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){ 
    // 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('Would be 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

[t-will-gillis]

See above. Mostly complete, might need minor revisions.

Linked to How to Contribute to the Wiki

[t-will-gillis]

Closing as completed.