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

[t-will-gillis]

Dependency

• [x] #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.

NOTE Everything below is DRAFT.

Action Items

• [x] Refer to #4819 and the template illustrated in #4841
• [x] DRAFT Make sure summary HfLA GitHub Actions page is referring to correct info-
  • [x] Name is not "update team members", it is now schedule-monthly.yml.
  • [x] The link needs to be updated OR completely replaced
• [x] ~Needs the page link describing the schedule-monthly.yml.~ SEE BELOW
• [x] ~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, #4819
• This issue also addresses remaining items noted in ER #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[bot]]

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

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 removed 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)

Labels Used by Workflow

• Complexity: Small
• size: 0.5pt
• role: dev leads
• Feature: Administrative
• Feature: Onboarding/Contributing.md

Tokens Used by Workflow

• HACKFORLA_ADMIN_TOKEN ( in schedule-monthly.yml )
• HACKFORLA_BOT_PA_TOKEN ( 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 on the first day of every month, except January. (January is omitted because the 'website' team takes off the month of December. 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.
    • 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 if the member does not show any activity within the last two months:
    • It checks whether the member's username is listed on the 'website' team; if not the person is added. (We want to make sure that we don't remove a member that was never added to the 'website' team)
    • If the team member is on the list of inactiveWithOpenIssue and the issue is not a "Pre-work Checklist", their name and issue are added to cannotRemoveYet. (We don't want to remove the person with an open assignment)
    • If the team member is not on the previouslyNotified list, 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() runs a second time to update the list of updatedTeamMembers.
  • The function notifyInactiveMembers() iterates through the list of updated team members and if the member does not show any activity within the last month:
    • It checks if the member cloned HfLA's repo in last month. If so, then the member might be new and are still setting up they will not be notified of inactivity yet.
    • 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 member 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 worksheets in the "hackforla-bot@hackforla.org" account complement this workflow:

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

Test Procedure

• [ ] 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

[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.