search

hackforla / website

Hack for LA's website
https://www.hackforla.org
GNU General Public License v2.0
323 stars 775 forks source link

Update documentation for wins_data #7707

Open dcotelessa opened 1 week ago

dcotelessa commented 1 week ago

Overview

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

Action Items

Resources/Instructions

Rundown of wins data local environment set up - https://github.com/hackforla/website/pull/7615#issuecomment-2425762934

github-actions[bot] commented 1 week ago

Hi @dcotelessa.

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

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:

dcotelessa commented 1 week ago

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

  1. 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 https://github.com/hackforla/website/issues/5746#issuecomment-1846549069

  1. 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 https://github.com/hackforla/website/issues/4134#issuecomment-2365343902 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 https://github.com/hackforla/website/issues/5746#issuecomment-1846549069 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 https://github.com/hackforla/website/issues/4134#issuecomment-1741851926 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

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

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

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

  4. 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 Githubissues.

  5. Githubissues is a development platform for aggregating issues.