Troubleshooting document

What happens if the spreadsheet link changes?

1. The spreadsheet link is an environment variable in the prod environment.
2. Go to Settings > Environments
3. If an environment called prod doesn't exist, create it
4. Click into the prod environment
5. Under Environment variables, click the pencil next to ROSTER_SHEET_LINK if the environment variable exists, or Add environment variable if it currently does not exist
6. In value, paste the link of to the Google sheet that is used for rostering

   Make sure that the Google sheet has view permissions for everybody

7. If you're running locally, also change the local environment variable ROSTER_SHEET_LINK in your .env file.

Valid Roster Sheet Format

The script reads a single row from the sheet that corresponds to a specific Sunday.

Each row must contain 5 consecutive columns, with the following required fields:

Required Columns

Rows

• Each row represents a different Sunday's service.
• The script identifies the correct row by matching the date in the first column.
• Ensure there is only one row per date.

Example Roster Table

You can add other rows/columns apart from these, but they will be ignored by the program

Help! The PowerPoint doesn't seem to be generated.

1. Go to the repo here.
2. Click the actions tab, which should list All workflows
3. Click the most recent workflow, and see its status
4. If there has been no runs within the past week - head down to the steps listed in The workflow didn't seem to have been run
5. If you see a red X, it means the workflow has failed. Try to see what occurred (invalid formatting or something else) and email panghowu@gmail.com with the error.
6. If you see a green workflow run in the past week, try to rerun the workflow using the steps outlined below.

The workflow didn't seem to have been run

1. From the Actions tab, click Create Powerpoint and push to main
2. There should be a small bar saying

   This workflow has a workflow_dispatch event trigger.

3. If this bar appears, click Run workflow at the right
4. Click the green Run workflow button to create a workflow manually
5. Wait for the workflow to finish running, then check its status. If it is green, then everything has worked and you can proceed. If it failed, then it may be better to proceed manually or download an old PowerPoint that you can modify and email panghowu@gmail.com with a screenshot of the error.
6. If it was green, the site should redeploy within a few minutes when the Deploy PowerPoint Site workflow finishes. Refresh and download the new powerpoint when it is done using the site.

Some parts of the powerpoint seem to be missing

This typically means that there was invalid formatting in the roster sheet. To fix it:

1. Check the spreadsheet to see if there are any invalid songs. These are any songs that are not in the songs directory
2. Check if the bible passage is valid and is typo free.
3. Rerun the workflow as highlighted in The workflow didn't seem to have been run above.

How do I add new songs?

1. This is probably the most troublesome part of this program, and is typically easier if you clone the repository and make changes locally. Nevertheless, it is possible to do this online if you follow the instructions very carefully.

If you need to add a new song on the day, it's probably better to just add it manually using PowerPoint and not this program.

These steps are for when you are adding a new song for future uses. Read it very carefully and follow the instructions as shown.

Steps for adding new songs using GitHub Web

1. Log into GitHub on an account with write permissions to this repository. If you'd like to be added as a collaborator email me or raise an issue panghowu@gmail.com
2. Click Add File --> Create new file
3. In the file path above, enter the path as

   smallPowerpointMaker/Songs/[YOUR SONG NAME]/[YOUR SONG NAME]_Lyrics.txt

   Ensure this is entered correctly. File paths aren't case sensitive, but please capitalise each word to follow naming convention.

   If you have a variant of a certain song, feel free to add it after to differentiate between songs, such as In Christ Alone and In Christ Alone (Passion)

   Typing the slashes ensures that GitHub creates and commits a new directory to store the text file in, which is what the program expects

4. Enter the Song title as the first line of the file
5. As the second line, keep it empty. Some older files has the CCLI number there but this has since been deprecated and isn't necessary to add for newer songs.
6. Enter the song with sections headers and lyrics. Some tips are below:

   Please ensure that each lyric is preceded by its section, such as Chorus, Prechorus, Verse 1, etc

   Each section MUST have square brackets surrounding them. This makes the program treat it as something different to song lyrics.

   By default, slides have 4 lines in them. To force a slide break and new slide, add a new section after the last lyric line.

   Try to ensure each line is less than 60 characters as long lines could overflow when slides are generated

   Do not include any unnecessary newlines, as these will be treated as text and hence create blank lines (unless that is what you want!)

7. Press Commit changes...
8. If this is a new song and this is being created in advance - click Create a new branch and create a description for the change.
9. If this is being created on the day/is an emergency, you probably should just add the song manually using powerpoint.

An example song (with some extra comments denoted by <--)

10000 Reasons (Bless the Lord) <-- Title on first line. All sections in parentheses are ignored by the program.
CCLI license number: 39384635 <-- The real CCLI number isn't needed here - but the line should be filled with something
[Chorus] <-- Song section header in square brackets to denote a new section
Bless the Lord oh my soul
Oh my soul
Worship His Holy name
[Chorus] <-- By ending at 3 lines, it makes a new section early. Useful for certain songs such as this one
Sing like never before
Oh my soul
I'll worship Your Holy name
[Verse 1] 
The sun comes up
It's a new day dawning
It's time to sing Your song again <-- You can also include a newline rather than explicitly setting a new section to force a new slide to be made

Whatever may pass
And whatever lies before me
Let me be singing
When the evening comes

Steps for adding new songs using GitHub codespaces or an IDE

1. Clone this repo

git clone <repo_link>

2. Set up a virtual environment (optional but recommended)

   python -m venv <environment_name>

3. Activate the virtual environment

   source <environment_name>/bin/activate On MacOS or Linux

   <environment_name>\Scripts\activate On Windows

4. Install required dependencies

   pip install -r REQUIREMENTS.txt

5. Generate a LyricsGenius API key here
6. Generate a client access token, and copy paste it as the value of the environment variable GENIUS_TOKEN into a .env file in the root of the project. You can get more information about using .env files here.
7. Ensure that all other environment variables are set up properly. Follow the instructions in the README.md file to see which environment variables you need to set up. Your .env file should looks like this:

   GENIUS_TOKEN=[THE TOKEN YOU COPY PASTED FROM THE GENIUS WEBSITE]
   ROSTER_SHEET_LINK=[THE SPREADSHEET LINK]
   ...
   

8. Run the song_finder script locally

python Scripts/song_finder.py

9. When prompted for a song name - input the name of the song you'd like to add
10. When prompted for an artist - input the name of the artist
11. A new text file should appear with the lyrics in a required format.
12. Feel free to add/modify the lyrics to suit your use case!

Be sure to follow all the conventions above. Using the program like this should allow inputs to be more consistent.

13. Commit the changes to a new branch and submit a PR. Remember that for the action to recognise the song it needs to first be in the main branch - so merge it if needed.

An example of running the program is shown here

python3 Scripts/song_finder.py
Input song name: Your will be done
Input artist name: CityAlight
Searching for "Your Will Be Done" by CityAlight...
...
Done.
Your Will be Done (Live)
CCLI license number: 35590026
[REST OF LYRICS!]

How do I run tests?

This program has no unit tests. Instead, tests are sanity tests designed to reflect if the final product works as intended. A limited set of songs will be used to validate if everything works fine

1. Clone this repo

git clone <repo_link>

2. Ensure that all environment variables are set up properly. You can create a new .env file to do this with the format. Follow the instructions in the README.md file to see which environment variables you need to set up.

   ENVIRONMENT_VARIABLE_1_NAME=ENVIRONMENT_VARIABLE_1_VALUE
   ENVIRONMENT_VARIABLE_2_NAME=ENVIRONMENT_VARIABLE_2_VALUE
   ...
   

3. Set up a virtual environment (optional but recommended)

   python -m venv <environment_name>

4. Activate the virtual environment

   source <environment_name>/bin/activate On MacOS or Linux

   <environment_name>\Scripts\activate On Windows

5. Install required dependencies

   pip install -r REQUIREMENTS.txt

6. Run new_powerpoint_maker.py and when it asks for test mode, input t
7. This should create a new directory TEST on your local machine, which will store all test files. View each one in order to see if the template looks good.