Add new section "Testing Wins in a test repository" to the Wins Apps Script Development Wiki Page

[roslynwythe]

Overview

As developers we need to explore the feasibility of creating a WINS development environment which connects to a test repository, so that issues and pull requests generated during testing will be created in the contributors fork of the website repository rather than hackforla/website. The proposed strategy is to modify gh-requests and to replace the secret key with the contributor's PAT.

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 section "Testing WINS in a test repository" to be added to the Wins Apps Script Developement Guide¹. In it, detail instructions for using the developer's repository for testing Wins Apps Script code. The instructions should include these elements:
  • Generating a PAT (Personal Access Token) to replace the production repo secret key
  • creating branches for pushing updates to _wins-data.json and for testing JSON data
  • modifying code to push updates to the test branch
  • modifying code to create PR in the test repo instead of hackforla/website
  • modifying code to create issues in the test repo in response to new wins form submissions
• When the test environment is ready and the above elements can be demonstrated, move this issue to the "Questions/In Review" column and apply the "ready for dev lead" label.
• Demonstrate the above elements test for the dev lead.
• Upon approval from dev lead, add the link to the draft to How to Contribute to the Wiki

Dev Lead/Merge Team

• Be sure to revoke all access rights from the developer once copies of required documents have been made.

Resources/Instructions

Footnotes

1. Wins Apps Script Development Guide ↩

[roslynwythe]

Testing Wins in a test repository

This process enables a developer use their fork of the website repository as the destination for Wins JSON data, pull request and issues, so that during testing the developer can run main() in the wins-form-response Apps Script without requiring access to the production bot token.

The process can be summarized as follows. Depending on the test procedure, some or all of these elements may be required:

1. Prepare branches in the website fork of the developer's (test) repository
2. Replace the production secret key with a PAT
3. Modify ghrequests to create commits, pull requests and issues in the test repository
4. Modify winsFormResponse to target the developer's Project Board
5. Continue following steps in Create wiki page "Hfla Google Apps Script Development/Review Process" #4134 (comment) for logging into Google Drive, making copies of the documents into a test environment folder, and editing/testing code. Perform testing as required by your issue. This may require examination and merging of a Pull Request in the test repository, then pulling down the resulting branch and testing locally using Docker.

1. Prepare the test repository

Create two new branches in the developer's fork of hackforla/website
a) Create a new branch "update-wins-data" to be used to receive pushed data from Google Apps Script
b) Create a new branch "test-wins" to act as the base for Pull Requests for end-to-end testing

2. Replace the production secret key with a PAT

a) In the developer's GitHub settings, in Developer Settings, generate a new token with scope public_repo and set the expiration long enough to last until the end of testing.
b) Copy the token then base64-encode it using the default settings at https://www.base64encode.org/
c) Copy the encoded key into a Google Doc named gh-key-test in your Google Drive

3. Modifying ghrequests to target test repository

a) In the functions: getSHA, updateWinsFile, and createPR, update url, replacing elizabethhonest with your github handle
b) In the function setToken_, replace both references to 'gh-key' to 'gh-key-test`

c) In the function createPR,

"head":  "<github-handle>:update-wins-data
"base":  "test-wins"

d) if you will be running createIssue, update the request url, replacing hackforla with your github handle in these functions: createIssue, addIssueToProjectBoardColumn

4. Updating Apps Script winsFormResponse:

a) remove the existing library ghrequests and in its place add a library using the scriptID of your modified ghrequests. The scriptID of a Google Apps Script project can be found in the Project Settings page. Never share a scriptID publically.
b) if you will be running createIssue, update const COLUMN_KEYS with the columnID of the "Questions/In Review" column of your Project Board

5. Testing

If you run main() in Wins-form (Response), it will generate a PR and a new GitHub issue in the target repository. If you have modified gh-requests to target to a test repository, you should review the PR and merge into the "test-wins" branch. Then testing can be completed in the "test-wins" branch. You may need to bring up that branch locally using Docker.

[roslynwythe]

• I went ahead and prepared the instructions because they were necessary as a reference for Update wins Google Apps Script to format wins json feed #4035, a time-sensitive issue which is currently in progress.

[github-actions]

@roslynwythe

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, February 5, 2024 at 11:06 PM PST.}

[github-actions]

@roslynwythe

Please add update using the below template (even if you have a pull request). Afterwards, remove the '2 weeks inactive' 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, February 12, 2024 at 11:05 PM PST.}

[github-actions]

@roslynwythe

Please add update using the below template (even if you have a pull request). Afterwards, remove the '2 weeks inactive' 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, February 19, 2024 at 11:06 PM PST.}

[github-actions]

@roslynwythe

Please add update using the below template (even if you have a pull request). Afterwards, remove the '2 weeks inactive' 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, February 26, 2024 at 11:06 PM PST.}

[roslynwythe]

This is ready for use as a reference in relevant WINS issues. Links to WINS Apps Script Development Guide and to this issue have been added to How to Contribute to the Wiki