Updating data (adding new members) - nfischer/framily-tree GitHub Wiki

It's fairly easy to add new members to the family tree. You can also follow these same steps to fix misspellings, update to use someone's preferred nickname, or whatever changes you need to make.

1. Request edit access for the spreadsheet. You can just email me at [email protected] and briefly explain who you are and that you're in Theta Chi fraternity at UCLA.

2. Once I grant edit access, visit the spreadsheet and add rows at the end of the doc for new members.

   • If you're deleting rows, let me know why over email (there could be good reasons for this, but I have to ask in case this was an accident).

3. Note: be careful to spell names consistently. Specifically, make sure you spell the big's name the same way it's spelled for their own row, and make sure you use consistent names/nicknames. As an example, the following would break the site because "Joe Miller" and "Joseph Miller" don't match (one row uses a nickname):

   name	big
   Joe Miller	Arthur Chase
   Alex Brown	Joseph Miller ⬅️ this row would fail because "Joe" and "Joseph" don't match.

   • To help get this right, the spreadsheet will actually autocomplete the Big's name (Column B) based on the values you've already filled in Column A. Just start typing a few letters of the Big's name and you'll see a suggestion to autofill.
   • It's OK to update old rows to change someone's name (like if they prefer a nickname). Just make sure to update every row with that person's name so the spreadsheet stays consistent.

4. In the top toolbar of the google sheet, there should be a menu option saying "Framily Tree". Once you feel satisfied with your edits, hit the "Update Website" option to update the data on the site.

   • The "Validate Spreadsheet" option checks for any typos or errors in the spreadsheet, highly recommend running this as you edit to make sure you don't make any errors, but the next menu option runs this as well anyways to double check before updating the live site. Any errors will be marked in red on the spreadsheet.
   • When the spreadsheet looks the way you want it, click the Update Website option to publish the changes to the website. To share some details of how this works this button will repeat the "Validate Spreadsheet" step, then it calls the GitHub API to activate a workflow to pull the spreadsheet data into the GitHub repo, and finally it pushes the change to the gh-pages branch. The changes should be visible after 30 minutes on https://nfischer.github.io/framily-tree/ (make sure to refresh the page).

Upon your first use of this menu, you may run into a pop-up asking you to authorize the script to run. Follow through and grant all permissions! This will let the Google App script run to let us update the site. See photos below as a walkthrough.

• Follow through with the pop-up asking to authorize.
• Select your Google Account that you have editor access with.
• It's going to say Google hasn't verified the app and try to get you to go back to safety, instead hit the Advanced option.
• Select the "Go to Theta Chi Brothers (unsafe)" option.
• Grant ALL of the permissions and checkboxes necessary. This will default to warn you about accessing all of your documents, but in reality the script actually only runs on this one specific spreadsheet.

Once you have run the Update Website option, the changes should be live on https://nfischer.github.io/framily-tree/ after 30 minutes. Please make sure to wait 30 minutes and then refresh the page. If you still don't see your changes on the website, then please send me an email so I can troubleshoot for you and look into the issues.

• This should create a popup message which tells you exactly where the errors are. The errors should also be highlighted directly on the spreadsheet (look for the cells highlighted in red).
• If you see some errors but you're not sure what's wrong, then the two most common mistakes to check for are: a. Did you use someone's nickname (or full name) when an earlier row used something else? For example, if one row uses the name "Joe Miller" but another row uses "Joseph Miller," then you should change both rows to the same name/nickname. b. If the rows look the same, then click in the row to see if there is an extra space at the end of someone's name or between their first and last name. You need to trim out unnecessary spaces. For example, "Joe Miller" is good, but " Joe Miller", "Joe Miller", "Joe Miller " are going to cause data validation errors.
• If you don't see any errors, then send me an email so I can help look into it.

• Look at https://github.com/nfischer/framily-tree/pulls?q=sort%3Aupdated-desc+is%3Apr+author%3Aapp%2Fgithub-actions+. What you should see are some rows where it says data: Update framily data from Google Sheet (automated) and it has a purple icon to the left. If you see any which have a green icon, then that means the data still is not merged. You can click into that, scroll to the bottom, and it should tell you if there are any failing validation checks. If validations are failing, then you can click into specific ones to see a more detailed explanation of the problem.
• If only one or two validations are failing but the rest are passing, then contact me to look into it.
• If all the validations are failing, then see what the error says. It might be a data entry error, in which case you can fix it in the spreadsheet and click Update Spreadsheet again.
• When in doubt, just reach out to me to look into the issue.

If everything else worked but https://nfischer.github.io/framily-tree/ still doesn't show the changes, then here are two things you can try:

1. Try a hard refresh. The way to do this is to hold down the shift key and click the refresh button in the browser. This forces the browser to refresh the page even if it has it in the local cache. At time of writing, GitHub pages uses cache-control: max-age=600 to cache the website. This means that if you load the site in your browser, update the website, and do a "normal" refresh in your browser within 10 minutes (600 seconds), you'll still see the old data. A "hard" refresh should avoid the issue, however.
2. Try visiting https://nfischer.github.io/framily-tree/?refresh=true instead. GitHub pages uses a CDN (Content Delivery Network) which can cache the site for up to 30 minutes. So even if you do a hard refresh, you might still get the old family tree. You may be able to workaround the CDN cache by visiting https://nfischer.github.io/framily-tree/?refresh=true. The ?refresh=true part at the end is called a URL query parameter: using any URL query parameter with any value is enough to trick GitHub's CDN into refreshing its cache, so ?foo=bar works just as well.

If that doesn't fix it, send me an email.

You can skip reading this section. This is obsolete now that we have an automated workflow. I'm keeping these steps documented only in case the workflow fails at some point in the future.

Before the automated workflow, I had steps to manually pull the spreadsheet changes into the repo. This isn't too hard for me to do, I'm just writing down these notes so I don't forget. If you're a technical person and you're feeling up to it, feel free to try this out yourself and create a GitHub Pull Request.

In a terminal:

git pull origin main
npm install
# Pull down the spreadsheet data, convert this to a JSON file.
npm run getData
# This performs some minimal consistency testing on the spreadsheet data. This
# catches most typos.
npm test
# Start a local HTTP server and launch your web browser. You can manually test
# that the new brothers show up in the family tree where you expect.
npm start

# If everything looks good, then (1) commit the changes, (2) push to the main
# branch, (3) deploy the changes to the website.
git commit -am 'Update data'
git push origin main
npm run deploy