Create Wiki page to fill in missing GHA documentation: Issue Trigger

[roslynwythe]

Overview

We need to separate the wiki content for the issue trigger workflow¹,²,³ into two parts corresponding to the two jobs within the workflow: Add Missing Labels to Issues and Ask for Preliminary Update

Action Items

• 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
• In a comment in this issue, create a draft of a new wiki page"GHA: Add Missing Labels to Issues" using the template below. Much of the content can come from the page GHA: Issue Trigger¹
• In a comment in this issue, create a draft of a new wiki page "GHA: Ask for Preliminary Update" using the template below
• Copy the contents of the page HfLA GitHub Actions² to a comment in this issue then edit the section under "issue trigger". The new content should consist of two bullet points:
  • The first bullet should summarize the function of the job Add Missing Labels to Issues and will link to the corresponding new page
  • The second bullet should summarize the function of the job Ask for Preliminary Update and will link to the corresponding new page
• Copy the contents of the page GHA: Issue Trigger³ to a comment in this issue then edit it to reference the content in the two newly created wiki pages.

Resources/Instructions

Template for GHA documentation

## Summary
-
### Scheduled
-
### Workflow
-
### Supporting Files/Folders
-
### Labels
-
### Test Procedure

Footnotes

1. https://github.com/hackforla/website/blob/gh-pages/.github/workflows/issue-trigger.yml ↩ ↩²

2. HfLA GitHub Actions ↩ ↩²

3. GHA: Issue Trigger ↩ ↩²

[github-actions]

Hi @A-Wu5, 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 :)

[A-Wu5]

i. Availability T-Sunday evenings
ii. ETA: I'm not exactly sure yet. I'll have a better understanding by the end of the week if I do not finish it by then.

[A-Wu5]

GHA: Add Missing Labels to Issues

Summary

• Check if an issue has the four required labels: a 'Feature/P-Feature' label, a 'Size' label, a 'Role' label, and a 'Complexity' label. If not, add the corresponding 'missing' labels and post a comment about adding missing labels. If the issue has all three labels, post a comment that congratulates and gives more details about the project board

Scheduled

• Issue opened

Workflow

• issue-trigger.yml

Supporting Files/Folders

• Supporting Files Folder: trigger-issue/add-missing-labels-to-issues
• Support File obtain-labels.js located in utils folder (Check if obtain-labels.js file is still being used in this workflow)

Labels

• Feature Missing, role missing, size: missing, Complexity: Missing,

Test Procedure

See below comment

[A-Wu5]

GHA: Ask for Preliminary Update

Summary

• Thanks contributer for taking up the issue. Asks contributer to comment on issue their availability and ETA to complete the issue. Additionally, reminds the contributer only work on one issue at a time.

Scheduled

• Assign issue

Workflow

• issue-trigger.yml

Supporting Files/Folders

• Supporting Files Folder: trigger-issue/add-preliminary-comment

Labels

Test Procedure

[A-Wu5]

HFLA Github Actions

Workflows are yaml files

Supporting files can be

• js
• json
• md
• gitkeep

Template for GHA documentation

## Summary
### Scheduled
-
### Workflow
-
### Supporting Files/Folders
-
---
Back to [HfLA GitHub Actions](HfLA-GitHub-Actions)

Hack for LA's GHAs

add update label weekly

• Checks the in-progress column from the project board. Goes through each issue, and if there is an assignee, checks the timeline for the issue. If it is outdated, posts a comment to update the issue and ensures the label is changed to 'to update.' Else, change the label so it is 'updated'

github data

• Generates a new github-data.json and commits that to the repository

issue trigger

• Add Missing Labels to Issues

  Check if an issue has the four required labels: a 'Feature/P-Feature' label, a 'Size' label, a 'Role' label, and a 'Complexity' label. If not, add the corresponding 'missing' labels and post a comment about adding missing labels. If the issue has all three labels, post a comment that congratulates and gives more details about the project board

• Ask for Preliminary Update

  Thanks contributer for taking up the issue. Asks contributer to comment on issue their availability and ETA to complete the issue. Additionally, reminds the contributer only work on one issue at a time.

lint-scss

• Checks and lints modified scss files in PRs

move closed issues

• Moves a closed issue into either the QA or Done column of the project board. If the issue has a “hard” label (Feature: Refactor CSS, Feature: Refactor HTML, Feature: Refactor JS / Liquid, Feature: Refactor GH), the issue is moved to the Done column. If the issue has no “hard” labels but does have an “override” label (role: front end), the issue is moved to the QA column. If the issue has no “hard” or “override” labels and does have a “soft” label (role: back end/devOps, Feature: Analytics), it is moved to Done. All other issues are moved to QA

pr instructions

• Creates an instruction on how to get a copy of a PR branch for review, then uploads the results into an artifact

pull request trigger

• An open script that could be triggered when a pull request is closed on the following branches 'gh-pages', 'feature-homepage-launch', 'feature-tech-dropdown'

set pr labels

• RegEx takes the issue number on the body of the PR, and uploads the results (including labels on the issue) into an artifact

update team members

• Trim inactive members from the write team

vrms data

• Generates a new vrms_data.json and commits that to the repository

wr pr instructions

• Leaves a comment on new PRs with a link to the relevant documentation for reviewing PRs and the command line instructions for pulling down a new branch for review.

wr pull request trigger

• An open script that should house all the other scripts (workflows) that should be triggered when a pull request is closed.

wr set pr labels

• This workflow is triggered when workflow [Set PR labels] is completed. Downloads artifact for the completed workflow. Then, gets the PR and issue number from the downloaded artifact and uses an API request to get the labels. Lastly, puts the same labels into the PR.

Deprecated GHAs

no-labels-template.md

• Removed the no-labels-template.md file so that the total number of bot comments are reduced, and developers would have less notifications. Edited lines 47-55 in post-labels-comment.js so that no comment object was created when all the correct labels were added, and therefore no comment is posted.

---

extra folders or files with unknown workflows

• Supporting Files Folder: trigger-schedule - folder has one file .gitkeep and its empty - The .gitkeep was likely added as a way of forcing git to track the new empty directory when the person who created the GHA began working on it. This is not a supported feature of git and now that there is content in the directory, there is no real need for the .gitkeep file
  The commit message for the .gitkeep file is just “Create directory for gha refactor”

[A-Wu5]

GHA: Issue Trigger

Summary

• Adds 'Missing' labels to newly created issues to notify issue creator to add required labels.
• Asks contributer for a preliminary update when assigned an issue to gauge the time it might take to complete the issue.

Scheduled

• Issue opened and issue assigned

Workflow

• issue-trigger.yml

Supporting Files/Folders

• Supporting Files Folder: trigger-issue/add-missing-labels-to-issues
• Supporting Files Folder: trigger-issue/add-preliminary-comment
• Support File obtain-labels.js located in utils folder (Check if obtain-labels.js file is still being used in this workflow)

---

Back to HfLA GitHub Actions

[A-Wu5]

Blocker: I am confused on these steps:

• The first bullet should summarize the function of the job Add Missing Labels to Issues and will link to the corresponding new page
• The second bullet should summarize the function of the job Ask for Preliminary Update and will link to the corresponding new page.

It says to link the bullet to the corresponding new page, but the page has not been created/approved for creating. Currently in my comments, the URLS linked don't go anywhere. This also applies to the step for editing the HFLA Github actions page and GHA: Issue trigger page

Edit: Spacing

[A-Wu5]

Blocker: For the two steps where I am using the template given to create new pages, I am unsure what to put for Labels and Test Procedure.

[roslynwythe]

Hi @A-Wu5 great job so far. Don't worry about creating the links between the pages; that can be done later when the pages are incorporated into the new wiki. The "Links" section are fine but the "Test Procedure" sections need to be filled in and these are actually the most involved part of this issue. Below I've created a draft "Test Procedure" for "Add Missing Labels to Issues". Please review that, confirm the steps (doing an actual test if possible) and clean up the formatting as required. Then create something similar for the "Ask for Preliminary update", but that will be simpler because it does not require a secret token.

Also under "Supporting Files/Folders", please detail each individual file, noting for instance the general purpose of the .js and .md files. It doesn't look like obtain-labels.js is used but please confirm that.

Also in "GHA: Issue Trigger" please mention the logic that connects the steps, for instance the logic that checks if the assignee is on the website-write team, and the logic that checks if the issue has the appropriate 'role' labels. From glancing at the code now it appears that if the assignee is not on the website-write team or if the issue does not have an appropriate role label, the "missing" labels are added but no "added labels" or "missing labels" comments are posted. Please confirm and add that information. Thanks

[roslynwythe]

Draft - Test Procedure for "Add Missing Labels to Issues"

Step 1: Issue Branch

• Push your issue branch to your fork of the website repository, as described in Section 3.1.a of CONTRIBUTING doc, for example: git push --set-upstream origin update-missing-labels-1234

Step 2: Repository Settings and Labels

• Browse to your fork of the website repository and click Settings

  Screenshot of Repository Settings

  

• Change the default branch to the new issue branch

  Screenshot of Default Branch Setting

  

• Further down on the settings page under Features, check the Issues checkbox

  Screenshot of Issues Checkbox

  

• Browse to the Issues page, then click Labels

  Screenshot - creating labels in the test Repo

  

• Create labels from the "Complexity", "size", "role" and "Feature" series. The color of the labels don't have to match those on the hackforla/website repository, but the text of the labels must match exactly.

Step 3: Create Personal Access Token

The workflow file issue-trigger.yml requires a repository secret and so you will need to create your own personal access token (PAT) in your forked repository for testing in your repository.

1. Go to your "Settings"

2. Click on "Developer settings"

3. Click on "Personal access tokens" and then "Tokens (classic)"

4. Click "Generate new token" and then "Generate new token (classic)"

5. Now you can create a new personal access token

It is a best practice to set an expiration date for the token. Select the scope read: org

When the token is generated, copy it and place it somewhere safe so you don't lose it. The token will not be available again when you leave the page!!

6. Go to your repository and click "Settings"

7. Scroll down and click the "Secrets and variables" dropdown and click on "Actions"

8. Click on "New repository secret"

9. Name the secret `TEST_TEAMS` and paste the secret token into the textbox

Now, while you are testing the GitHub Action in your repository, you will replace secrets.TEAMS with secrets.TEST_TEAMS in issue-trigger.yml. Once you are satisfied with the changes in your own system, change it back to secrets.TEAMS before making your pull request so that token for the HfLA Project Board is not pointing to a secret that doesn't exist.

Step 4 Testing

• Create issues with various labels and confirm that if an issue has no labels from a required series ("Complexity", "role", "size" or "Feature"), the appropriate "missing" label is added and the appropriate comment is added.

[A-Wu5]

Thank you for the clarification! I see what I need to do now.

[A-Wu5]

Update

1. Progress - Working on draft for 'Ask for Preliminary Update'; Currently going through test procedure for 'Add Missing Labels' to reinforce understanding
2. Blockers - See above
3. Availability - M - F 12PM - 3PM
4. ETA - 11/10

[roslynwythe]

Hi @A-Wu5 I forgot to mention, when you have a draft for me to review, please send me a message on Slack or else put the issue in Questions/In Review and add the label "ready for dev lead". Thanks very much for your work on this issue!

[A-Wu5]

GHA: Add Missing Labels to Issues

Summary

• Check if an issue has the four required labels: a 'Feature/P-Feature' label, a 'Size' label, a 'Role' label, and a 'Complexity' label. If not, add the corresponding 'missing' labels and post a comment about adding missing labels. If the issue has all three labels, post a comment that congratulates and gives more details about the project board

Scheduled

• Issue opened

Workflow

• issue-trigger.yml

Supporting Files/Folders

• Supporting Files Folder: trigger-issue/add-missing-labels-to-issues
  • add-labels-template.md - Message template for reminding user to add required labels
  • check-labels.js - Checks labels and returns missing labels
  • post-labels-comment.js - Formats the missing labels into the message template and posts it to the issue

Labels

• Feature Missing, role missing, size: missing, Complexity: Missing,

Test Procedure

Step 1: Issue Branch

• Push your issue branch to your fork of the website repository, as described in Section 3.1.a of CONTRIBUTING doc, for example: git push --set-upstream origin update-missing-labels-1234

Step 2: Repository Settings and Labels

• Browse to your fork of the website repository and click Settings

  Screenshot of Repository Settings

  

• Change the default branch to the new issue branch

  Screenshot of Default Branch Setting

  

• Further down on the settings page under Features, check the Issues checkbox

  Screenshot of Issues Checkbox

  

• Browse to the Issues page, then click Labels

  Screenshot - creating labels in the test Repo

  

• Create labels from the "Complexity", "size", "role" and "Feature" series. The color of the labels don't have to match those on the hackforla/website repository, but the text of the labels must match exactly.

Step 3: Create Personal Access Token

The workflow file issue-trigger.yml requires a repository secret and so you will need to create your own personal access token (PAT) in your forked repository for testing in your repository.

1. Go to your "Settings"

2. Click on "Developer settings"

3. Click on "Personal access tokens" and then "Tokens (classic)"

4. Click "Generate new token" and then "Generate new token (classic)"

5. Now you can create a new personal access token

It is a best practice to set an expiration date for the token. Select the scope read: org

When the token is generated, copy it and place it somewhere safe so you don't lose it. The token will not be available again when you leave the page!!

6. Go to your repository and click "Settings"

7. Scroll down and click the "Secrets and variables" dropdown and click on "Actions"

8. Click on "New repository secret"

9. Name the secret `TEST_TEAMS` and paste the secret token into the textbox

Now, while you are testing the GitHub Action in your repository, you will replace secrets.TEAMS with secrets.TEST_TEAMS in issue-trigger.yml. Once you are satisfied with the changes in your own system, change it back to secrets.TEAMS before making your pull request so that token for the HfLA Project Board is not pointing to a secret that doesn't exist.

Step 4 Testing

• Create issues with various labels and confirm that if an issue has no labels from a required series ("Complexity", "role", "size" or "Feature"), the appropriate "missing" label is added and the appropriate comment is added.

[A-Wu5]

GHA: Ask for Preliminary Update

Summary

• Thanks contributor for taking up the issue. Asks contributor to comment on issue their availability and ETA to complete the issue. Additionally, reminds the contributor only work on one issue at a time.

Scheduled

• Assign issue

Workflow

• issue-trigger.yml

Supporting Files/Folders

• Supporting Files Folder: trigger-issue/add-preliminary-comment
  • check-label-preliminary-update.js - Checks if preliminary update comment needs to be posted
  • preliminary-update-comment.js - Formats the preliminary update comment and posts it depending if needed
  • preliminary-update.md - Template for preliminary update comment

Labels

• None

Test Procedure

Step 1: Issue Branch

• Push your issue branch to your fork of the website repository, as described in Section 3.1.a of CONTRIBUTING doc, for example: git push --set-upstream origin update-missing-labels-1234

Step 2: Repository Settings and Labels

• Browse to your fork of the website repository and click Settings

  Screenshot of Repository Settings

  

• Change the default branch to the new issue branch

  Screenshot of Default Branch Setting

  

• Further down on the settings page under Features, check the Issues checkbox

  Screenshot of Issues Checkbox

  

• Browse to the Issues page, then click Labels

  Screenshot - creating labels in the test Repo

  

• Create labels from the "Complexity", "size", "role" and "Feature" series. The color of the labels don't have to match those on the hackforla/website repository, but the text of the labels must match exactly.

Step 4: Testing

• Create new test issues that include a 'role: back end/devOps', 'role: front end', or 'role: design' label and assign self to issues to confirm preliminary comment is posted.

[A-Wu5]

GHA: Issue Trigger

Summary

• Adds 'Missing' labels to newly created issues to notify issue creator to add required labels.
• Asks contributor for a preliminary update when assigned an issue to gauge the time it might take to complete the issue.

Scheduled

• Issue opened and issue assigned

Workflow

• issue-trigger.yml
• When a new issue is created, this file checks if the required labels are present and adds corresponding Missing labels to the issue. If the user is apart of the website-write team, then a comment is posted to remind the user to add missing labels if needed.
• When a user is newly assigned to an issue, the file checks if the issue contains any of the labels: role: back end/devOps, role: front end, role: design, role: user research and posts a comment to ask user for their preliminary update.

Supporting Files/Folders

• Supporting Files Folder: trigger-issue/add-missing-labels-to-issues
• Supporting Files Folder: trigger-issue/add-preliminary-comment

---

Back to HfLA GitHub Actions

[A-Wu5]

Hi @roslynwythe. I've fixed my draft in the 3 comments above. I've followed your test procedure for 'Add Missing Labels to Issues' and the steps were very clear, so I added that to my drafts in the comment above with only a change to one of the screenshots.
I've noted the general purposes for each file under "Supporting Files/Folders" and I've confirmed that obtain-labels.js is not used in these files.

I've also described some of the logic for 'GHA: Issue Trigger' under the 'workflow' section. Please let me know if it is done correctly.

Thank you!

[roslynwythe]

Hi @A-Wu5 this looks great! There are just a few tiny things required to complete the issue.

• correct the misspelling of "contributor"
• write "none" under "Labels" for "GHA: Ask for Preliminary Update"
• go to the page How to Contribute to the Wiki and update the links for all three wiki pages.

[A-Wu5]

@roslynwythe I completed the tasks you mentioned above!

[roslynwythe]

Great job @A-Wu5 on completing this issue.