Create new Wiki for GHA update-label-directory.yml

[t-will-gillis]

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 "Create Label Directory" workflow.

Action Items

• Become familiar with HfLA's GitHub Actions main wiki page and HfLA GitHub Actions wiki page.
• Become familiar with create-label-directory.yml. Follow links to the yml and js files and understand the logic of the GHA.
• We are currently in the process of moving the old wiki to the new website-wiki repo, so we will not be making any changes or additions to the old wiki at this time. Thus, we will be adding wiki content through a different process now. Read How to Contribute to the Wiki. Follow the process given in How to Contribute to the Wiki when completing the remaining Action Items.
• On HfLA GitHub Actions wiki page make any necessary updates to the summary of [create-label-directory.yml], then review/update the [REPLACE WITH LINK TO GHA-SPECIFIC PAGE] page for accuracy and completeness, and add the new sections
  • "Labels" - List those labels on which the GHA depends or affects.
  • "Test Procedure" - Detail the process for testing the GHA in case there is a change in a dependent label/resources/package.

Resources/Instructions

• Hack for LA's GitHub Actions
• This epic is a result of ER ER: Request for Update of Hack for LA's Current GHA's Documentation #4728
• This issue is part of the epic to create GitHub Action Wiki pages Epic: Create GitHub Action Wiki pages #6403

[t-will-gillis]

Update Label Directory
_Workflow

Summary

The update-label-directory.yml workflow documents and manages the use of labels in the hackforla/website repository ('Repo labels') and ensures that the label-directory.json file ('JSON labels') and the Google Sheets 'Source of Truth' ('SOT labels') are kept in sync whenever a label is created, edited, or deleted in the hackforla/website repository. Specific details and functionalities are described below.

Trigger

• Workflow is triggered whenever a label is created, edited, or deleted from the hackforla/website repository.

Labels Used by Workflow

• all labels are used indirectly

Tokens Used by Workflow

• HACKFORLA_BOT_PA_TOKEN

Workflow Files

• update-label-directory.yml

  • update-label-directory.js (in utils folder)
  • label-directory.json (in utils/data folder)

  Complementary file (not part of workflow):

  • retrieve-label-directory.js (in utils folder)

Support File Folders

• .github/workflows
• github-actions/utils
• github-actions/utils/data

Background

This workflow and the supporting functions and documents surrounding it were created for these reasons:

1. The Repo Labels:
   • The labels used for issue-making, Project Board tracking, etc. for the hackforla/website repository are maintained in the repo itself and are referred to as the "Repo Labels". The "Repo Labels" are the current, actual labels that the repo 'knows about'.
   • Prior to the "Update Label Directory" workflow, our codebase often referenced label names (labelName): for example, workflows such as "Schedule Friday 0700" include functionality to add or remove specific labels from issues, and the new issue templates specify preliminary labels to attach when an issue is created. If we need to make an edit to the labelName in the "Repo Labels", then we would also need to search for and ensure that we edit the labelName in each place it occurs, otherwise the workflow may have crashed or we may not have had the correct default labels applied to new issues.
   • To avoid this situation we decided to create a JSON file of key:value pairs so that our workflows, new issue templates, and all other code could reference a labelKey rather than a labelName. With the JSON, we could change the labelName is many times as we wanted and not worry about changing the codebase, as long as the JSON file kept track.
2. The JSON Labels:
   • This workflow updates and uses a label-directory.json file, aka the "JSON Labels". The "JSON Labels" match labelKeys with labelNames, allowing the codebase to refer to a labelKey rather than a labelName. Accessory functions ensure that the labelKeys and the labelNames are coordinated.
   • When another workflow or template refers to a labelKey, the retrieve-label-directory.js utility retrieves the up-to-date labelName.
3. The SOT Labels: << Check link!
   • This workflow also sends data to a Google Apps Script, which in turn updates a Google Sheets worksheet named "Source of Truth Labels" Directory.

TO BE CONTINUED

Process

• The update-label-directory.yml workflow is triggered when a label is created, edited, or deleted in the hackforla/website labels.

TO BE CONTINUED

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, & 8.
• In addition to the 'files changed' in the PR, there are additional changes that you should make to help with testing.
• The create-label-directory.yml workflow requires a personal access token. Make sure that you have set up the token with the following scopes (see Tip 7):
  • HACKFORLA_BOT_PA_TOKEN scopes: admin:org_hook, public_repo
• In the same file, around line 13, replace 'hackforla' with your personal repo's specs.
• In the same file, around line 40 check that the website link is active.
• Note that although having all of HfLAs label is not necessary, Tip 8 explains a simple way to copy all of HfLA's labels to your own repo from the GitHub CLI.
• No other changes are needed for running the workflow.
• Suggested tests:
  • Go to your personal repo's label page at: https://github.com/<owner>/<repo>/issues/labels where 'owner' and 'repo' refer to your setup. Note- you do not need to match any labels, or even have labels yet. Do not attempt to edit the labels in the label-directory.json file. These match HfLA only.
  • Begin by selecting "New label" in the upper right. Enter the name, and optionally the description and color.
    • Select "Create label" and confirm that the new label is added.
    • Repeat with two other labels.
    • (FUTURE: add script to automatically create labels)
    • Next, open the label-directory.json and confirm that the new labels are added here is well (probably the last entries).
    • You can also review the "Action" logs to make sure there were no errors.
  • Next, select one of the labels you just created and change the color only. The "Action" log will run but there should be no changes.
  • Now, select on of your labels and change the name. The label should be changed in your repo and in the JSON file.
  • Finally, select on of your labels and delete it. The label should be removed from your repo, however in the JSON file it should be renamed "Your label" + " (deleted)", and the labelID should be reset to 9999999999.
• Refer to the "Source of Truth" document (at the link for the Google Sheets).
  • All of the changes you made should be detailed on the sheet with the tab titled "Worksheet: GitHub Label Updates Log", and edited, created, and deleted labels should be shown at the top of the "'SOT Labels' Directory" tab.

Testing Resources

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

[t-will-gillis]

In progress, pending PR #6442

[t-will-gillis]

In progress, pending PR #6442

[t-will-gillis]

Still pending #6442

[t-will-gillis]

Still pending #6442

[t-will-gillis]

Pending #6442

[t-will-gillis]

Pending completion of #6442

[HackforLABot]

@t-will-gillis

Please add update using the below template (even if you have a pull request). Afterwards, remove the 'To Update !' label and add the 'Status: Updated' label.

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures (optional): "Add any pictures of the visual changes made to the site so far."

If you need help, be sure to either: 1) place your issue in the Questions/In Review column of the Project Board and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel. Please note that including your questions in the issue comments- along with screenshots, if applicable- will help us to help you. Here and here are examples of well-formed questions.

_{You are receiving this comment because your last comment was before Monday, January 13, 2025 at 11:04 PM PST.}