Update documentation for wins_data

[dcotelessa]

Overview

We need to create documentation to set up current Wins Data for local testing

Action Items

• In comments, section is the instructions for wins data set up. Run through and test.
• Ensure we update the instructions for wins data with these instructions so we can sync:
  Create wiki page "Hfla Google Apps Script Development/Review Process" #4134 (comment)

Resources/Instructions

Rundown of wins data local environment set up - #7615 (comment)

[github-actions]

Hi @dcotelessa.

Please don't forget to add the proper labels to this issue. Currently, the labels for the following are missing:

• Complexity, Role, Feature, Size

NOTE: Please ignore this comment if you do not have 'write' access to this directory.

To add a label, take a look at Github's documentation here.

Also, don't forget to remove the "missing labels" afterwards.
To remove a label, the process is similar to adding a label, but you select a currently added label to remove it.

After the proper labels are added, the merge team will review the issue and add a "Ready for Prioritization" label once it is ready for prioritization.

Additional Resources:

• Wiki: How to create issues
• Wiki: How to read and interpret labels

[dcotelessa]

Instructions for Testing:

Overview
As a developer, to turn the wins card into a reusable component, we must first be able to generate a wins-data.json file of a more specific format. This issue is part of a series that aims to migrate us to the more specific format. The file _wins-data.json now implements the new data format, and so the file wins-data.json can be removed.

Action Items
Follow sections 1-2 in the Wins Apps Script Development Process1. Note that in this issue you will be modifying both Apps Scripts wins-form-responses and gh-requests so setup will be required in both /google-apps-script/wins-form-responses and /google-apps-script/gh-requests

1. Creating an issue branch
   a. Open your local command line/terminal and navigate to where you have the Hack for LA project located
   b. Create an Issue Branch in the usual manner, from an updated version of gh-pages
2. Installation of npm modules
   a. If not already installed, download and install node.js and npm

b. Cd to folder google-apps-scripts . Note that it contains two sub-directories, one corresponding to each Google Apps Script project:

gh-requests
wins-form-responses
c. Install clasp and the associated npm packages. This must be done in each subdirectory corresponding to an Apps Script project that you will be modifying. For a local install use npm install and note that you may have to prefix clasp commands with npx, for example: npx clasp login, npx clasp push, etc. For a "global" install run npm install -g.

Follow section 3 in the Wins Apps Script Development Process1. As described in section 3a and 3b, you will provide a dev lead with the google account you wish to use for testing, and request the dev lead to:

do not modify folder level access
share the Wins Form Admin Guide2 as VIEWER
share the Wins-form (Response)3 sheet as VIEWER
share the gh-requests doc as VIEWER
3. Preparation of test environment on developer's personal Google Drive
Select (or create) a google account to use for testing. In the testing process it will be necessary to authorize script access to your Google Drive, so you may choose to use (or create) an account separate from your personal google account. Authorization problems can occur if you are logged into multiple Google accounts, so we suggest that you log out of all google accounts then log in using the account you have selected for testing. This needs to happen anytime you want to work with the App Script on the files.

Ask a team lead to share the files required for the issue, providing a Google email address of the selected test account. The required documents may have been listed in the issue, but guidelines are provided below:

To understand the WINS project components, the WINS Form Admin Guide is helpful
Note to team lead: share the WINS Form Admin Guide with the developer as VIEWER
It will almost always be necessary to include Wins-form (Responses) sheet which contains the submitted form data, formatted Review data, and the Apps Script winsFormResponse
Note to team lead: share Wins-form (Responses) sheet with the developer as VIEWER.
If it will be necessary to test using new test form submissions, then the form Wins-form is required
Note to team lead: make a copy of Wins-form, including the issue # in the name, then share that copy with the developer as EDITOR.
If it will be necessary to modify the Apps Script-GitHub interface or to use that interface for testing (posting issues and/or wins data feed to a GitHub repository), then the Google Doc gh-requests will be required. This doc is the container for the Apps Script ghrequests.
Note to team lead: share gh-requests with the developer as VIEWER.
Continue following instructions in 3c and d. As described in 3d, you will have to make modifications to certain documents in the test folder.

It will not be necessary to restore any triggers, because you can execute main() in debug mode.
Since you will be running main() for testing, you must follow instructions in #5746 (comment)
3. Preparation of test environment on developer's personal Google Drive (cont.)
c. Copy required documents Once you receive the necessary shared Google Drive files, make copies of the required documents, placing the copies in your test folder within your Google Drive of the account you selected/created.

d. The following must be done to prepare the test docs for test

When Wins-form (Responses) is copied, the triggers are lost so you may need to recreate some triggers for testing - see #4134 (comment)
Make note the scriptID of the winsFormResponse script project from the Project Settings page, for later use with clasp
If the test environment includes a version of Wins-form, edit the Response settings so that form data will be stored in the test environment's Wins-form (Responses) sheet
If gh-requests is part of the test environment, and the developer is not on the merge team, it is necessary to follow the steps in #5746 (comment)
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:

Prepare branches in the website fork of the developer's (test) repository
Replace the production secret key with a PAT
Modify ghrequests to create commits, pull requests and issues in the test repository
Modify winsFormResponse to target the developer's Project Board
Continue following steps in #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 (next to other files you copied)

3. Modifying ghrequests to target test repository
   a. In the functions: getSHA, updateWinsFile, and createPR, update url, replacing elizabethhonest with your github handle (if your personal repo has a different name than website, replace)
   b. In the function setToken_, replace both references to 'gh-key' to 'gh-key-test'
   c. In the function createPR,

"head": ":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 (if your personal repo has a different name than website, replace

• (addIssueToProjectBoardColumn is not local?)
  e. SAVE your changes to your local file. (Click the "disk" icon.)

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.

Login and clasp Continue following instructions through section 6 "Editing". As described in this section, editing can be done locally in an IDE or in the Google Drive cloud editor, and the clasp utility can be used to transfer code back and forth between the local worksation and the Google Drive as needed.
4. Login to Google Drive with clasp login
Make sure you are working in a sub-directory in which you have installed the packages described above in "Installation of npm modules".
google-apps-scripts/gh-requests
google-apps-scripts/wins-form-responses
Run clasp login
If successful your local machine should automatically open a new browser tab to sign in to your Google Drive account
You will then select (or add) the account that you used in step 3a to save test documents in your test folder, and authorized Google Apps Script CLI for the scopes listed.
5. Cloning Google Apps Script using clasp
Cloning is the initial copying of Apps Script and metadata from the Google Drive (cloud) to the local workstation and must be done in the corresponding sub-directory of google-apps-script. Cloning is necessary only for those Apps Scripts that will be modified by your issue, and will not be required if you modified Apps Script just for testing purposes. If your issue calls for modifying and committing multiple Apps Scripts, you will repeat this procedure in each sub-directory.
Before the clone you must delete any existing version of the metadata by running rm .clasp.json
Run clasp clone <Script ID> where ScriptID is the scriptID of the source Google Drive Apps Script project
Script ID can be found in the project settings page in the Apps Script project in Google Drive
This process is used to confirm that prior to modification, the cloned Apps Script matches the script in the git repository. It is necessary to perform this step for each Google Apps Script project that you will be committing to the git repository.
Run git diff Code.js. Copy/paste the results of this command in a comment in your issue along with the name of the Apps Script. The warning LF being replaced by CRLF can be ignored, but if any actual file differences are reported, they must be examined to ensure that they are changes you made for testing purposes. If that is not the case, comment-mention a dev lead.
6. Editing code
You have two options for editing code
a. Local code editor
Note that Google Apps Script code cannot be tested locally; to test, use clasp push to push code to the Google Drive
b. Google Apps Script Cloud Editor (ie Google Drive UI)
run clasp open or browse to the container from Google Drive UI
Note that code must be committed locally; use clasp pull to bring code to the local system.
to push script to Google Drive, run clasp push
to pull script locally, run clasp pull
Go to the Google Apps Script (in Wins-Form Responses you copied in your Google Drive)which generates both the KVF and AF file.
Change any settings or code such that the AF version is no longer generated.
Refer to Section 7 "Testing" in the Hfla Google Apps Script Development Process Guide[^4] , Test the code by running main() in debug mode. A new pull request "Update wins-data.json via Google Apps Script" should be appear in your test repository. Examine the json data and if it looks good, merge into your repository test branch, bring that branch down to your local workstation and and use Docker to examine the resulting Wins page, which should remain unchanged.
7. Testing
a. Perform testing and demonstration as required by your issue.
b. If you run main() in Wins-form (Response), it will generate a Pull Request and new GitHub issue in the target repository.

If you are using a test respository, see Section 5 of [Testing Wins in a test repository}(https://github.com/https://github.com//issues/5746#issuecomment-1846549069)
If you are a merge team member testing against the production hackforla/website repository, make appropriate comments in the resulting PR and issue. Apply the label Ignore: Test to the issue.
Refer to Section 8 "Completing an Issue" in the Hfla Google Apps Script Development Process Guide[^4] , for information about commiting Code.js and creating a pull request.
8. Completing an issue
a. Following a successful demonstration, changes may be required before committing the Apps Script code. If you are following instructions in "Testing WINS in a test repository", you need to revert or reverse the changes you made to target the test repository or test Project Board. It may be helpful to refer to the output of the git diff command from step 4 under Cloning Modified Google Apps Script using clasp
b. Commit modified code using git and push the issue branch in the usual manner

do not add any files other than Code.js to the commit.

Refer to Part 3: Pull Requests in the contributing guide: https://github.com/hackforla/website/blob/gh-pages/CONTRIBUTING.md

On the Pull Request, add the label "ready for dev lead"
c. In your Pull Request, please describe your test setup/strategy

In the pull request, provide links to the "Update wins-data.json via Google Apps Script" Pull Request and also the Wins page (both in your repository), for the convenience of reviewers.

Release dependency on Google Apps Script: Migrate Wins Data - Delete AF file #2148

Footnotes
Wins Apps Script Development Process ↩ ↩2

Wins Form Admin Guide ↩

Wins-form (Response) Sheet ↩

[daras-cu]

@dcotelessa thank you for creating this issue. I started to read through your comment, but I think what we need is to clarify the general Wins Apps Script Dev Process rather than the specific instructions for #2147.

I know while working on #2147 you and Roslyn talked about parts of the process that were unclear, so you should use this issue to write out the changes you'd suggest making to Wins Apps Script Dev Process to help future developers working on Wins issues. After that I'll go through your changes and add anything additional that I came across while working through #2385.

It would be helpful to copy the sections you are editing and then put your re-written section below them so it's clear what's changing and we can discuss each individually, i.e. something like:

Current section 1a:

a. Open your local command line/terminal and navigate to where you have the Hack for LA project located

Proposed change:

a. Open your local command line/terminal and navigate to your Hack for LA project folder

Let me know if that makes sense!

[daras-cu]

@dcotelessa I started to work on some edits to the instructions in this Google Doc. You should be able to add suggestions as well, let me know if you are not able to.