Instructions for Viewing the Website through a Forked Repo's GitHub Pages

[JessicaLucindaCheng]

Overview

As developers, we need instructions for how to view code changes to the website through a forked repo using GitHub Pages so that developers who are unable to use Docker to view code changes can have another option.

Action Items

Developer

• In a new comment, write instructions for how to view code changes through a forked repo using GitHub pages and add a link to in ¹ in the Resources/Instructions section
  • Include possible pros and cons of this method

Tech Lead

• Read through the instructions and decide
  • 1) If we want to allow developers to use this method
  • 2) Depending on the decision for 1, determine the next steps for this issue, such as whether to add to website-wiki or CONTRIBUTING.md, closing the issue as not planned and add a decision record to the website-wiki, etc

Resources/Instructions

• https://pages.github.com/
• Graphics and Annotations for Issue 6219 starting with slide 12

Footnotes

1. Link to comment with instructions: https://github.com/hackforla/website/issues/6219#issuecomment-1925670289 ↩

[JessicaLucindaCheng]

Prerequisites

These instructions assume the following:

1. You are not using your personal GitHub Pages website at https://{YOUR GITHUB HANDLE}.github.io, where your {YOUR GITHUB HANDLE} is your GitHub handle.
2. You are okay with your personal GitHub Pages website showing the Hack for LA website content (at least temporarily).
3. You have already forked the hackforla/website repo. If you have not done so, follow the instructions in 1.3 Dev setup (3): Fork the repository in the How to Contribute to Hack for LA Guide.
4. You have already read our How to Contribute to Hack for LA Guide and understand
   • how to use git commands to change branches
   • how to add, commit, and push code changes to a branch on your forked repo.

Instructions

1. In your local IDE, go to the branch with your code changes.

2. In _config.yml file, edit the following line of code

   From

   url: https://www.hackforla.org
   

   To

   url: https://{YOUR GITHUB HANDLE}.github.io
   

   where your {YOUR GITHUB HANDLE} should be replaced with your GitHub handle. Then, push your changes to your forked repo.

3. On GitHub, go to your fork of the hackforla/website repo, which should be at

   https://github.com/{YOUR GITHUB HANDLE}/website
   

   where your {YOUR GITHUB HANDLE} should be replaced with your GitHub handle.

4. Select Settings.
   

5. Under General, find Repository name.
   

6. Edit the Repository name
   From

   website
   

   To

   {YOUR GITHUB HANDLE}.github.io
   

   where your {YOUR GITHUB HANDLE} should be replaced with your GitHub handle. Then, select Rename.

7. In the left menu, select Pages to navigate to GitHub Pages.
   

8. Under Build and deployment, find Branch.
   

9. Change the branch from gh-pages to the branch with the code changes you want to see. Then, select Save.

10. Wait a few minutes for the page to deploy before going to

    https://{YOUR GITHUB HANDLE}.github.io
    

    where your {YOUR GITHUB HANDLE} should be replaced with your GitHub handle. You can view the last deployed time and a link to view the code changes to the website on your forked repo at the top of GitHub Pages.
    

11. When done viewing the code changes, make sure to reverse changes made in

    • Step 9 by changing the branch back to gh-pages under Build and deployment (optional)
    • Step 6 by changing your Repository name back to website. The reason is that the naming convention of your repo follows the instructions in the CONTRIBUTING.md, which will make referencing instructions in our CONTRIBUTING.md and wiki pages easier for you in the future
    • Step 2 by changing the url back to url: https://www.hackforla.org in _config.yml before you submit a pull request

Notes

Pros

• Developers with issues with Docker can view code changes using GitHub Pages.
• While testing a WINS issue, a developer can push _wins-data.json to their fork, merge, and then verify operation of the wins webpage

Cons

• The developer is not using their personal GitHub Pages website at https://{DEVELOPER'S GITHUB HANDLE}.github.io, where {DEVELOPER'S GITHUB HANDLE} is the developer's GitHub handle.
  • If they are using their personal GitHub Pages website, they'll have to rename their repo with their personal website to something else temporarily to follow the instructions above. This is not recommended, especially if the developer has their website linked elsewhere and people going to their website would see Hack for LA website content instead of the developer's personal website.
  • Alternatively, the developer can use a different GitHub account to fork their fork of the website repo from their main account. Then, they can use their fork in their other GitHub account to follow the instructions above.
• The developer is okay with their personal GitHub Pages website showing the Hack for LA website content (at least temporarily).
• Having to edit url: https://www.hackforla.org in _config.yml to view code changes and then having to change it back before submitting a pull request.

[JessicaLucindaCheng]

@roslynwythe

• I have written instructions for how to use GitHub Pages to view code changes instead of using Docker. See this comment: Instructions for Viewing the Website through a Forked Repo's GitHub Pages #6219 (comment)
• I will assign you to this issue too because the rest of the Action Items I wrote are decisions you will have to make.

[ExperimentsInHonesty]

@JessicaLucindaCheng I think that part of these instructions are based on the assumption that you can only have one https://{YOUR GITHUB HANDLE}.github.io But the reality is you can have as many as you need - see the new ones I just made to show you
https://experimentsinhonesty.github.io/example1/
https://experimentsinhonesty.github.io/example2/

Where example1 is the name of the repo.

[JessicaLucindaCheng]

@ExperimentsInHonesty

@JessicaLucindaCheng I think that part of these instructions are based on the assumption that you can only have one https://{YOUR GITHUB HANDLE}.github.io But the reality is you can have as many as you need - see the new ones I just made to show you https://experimentsinhonesty.github.io/example1/ https://experimentsinhonesty.github.io/example2/

Where example1 is the name of the repo.

You're right that GitHub Pages can display content from multiple repos for one person's GitHub account in the way you mentioned. However, I have not figured out a way to view code changes to the website using https://{YOUR GITHUB HANDLE}.github.io/website with the current code/setup we have for the website. The instructions I have written were just the way I figured out how to do it and there may be a better way to do it.

[roslynwythe]

Thank you @JessicaLucindaCheng - it worked perfectly! I never would have thought of renaming the repository! I think this will be very useful and would support incorporating it into CONTRIBUTING.md or else creating a wiki page and linking to that page from CONTRIBUTING.md.

[ExperimentsInHonesty]

• Have someone create a github org
• create a repo called test1
• create a repo called test2
• turn on ghpages for each (using the deploy from branch auto static html
• add a hello world html page for each with the name of the repo on it
• make sure they both resolve
• then have them fork, their fork of the website into a new repo in the org
• apply instructions to see if making the repo name be [orgname].github.io breaks the other two sites

[JessicaLucindaCheng]

Tasks

Test the impact on {ORG NAME}.github.io/{REPO NAME}

• Have someone create a GitHub org
• Create 2 repo
  • One called test1
  • One called test2
  • Note: These repos need to be public to use GitHub Pages with a GitHub Free.
    • Source: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
      
• Add a Hello World HTML page for each with the name of the repo on it. The file should be named "index.html".
• Turn on GitHub Pages for each (using the deploy from branch auto static HTML)
• Make sure they both resolve
• Then have them fork, their fork of the website into a new repo in the org
• Apply instructions to see if making the repo name be {ORG NAME}.github.io breaks the other two sites

Answer:

• It doesn't break {ORG NAME}.github.io/test1 and {ORG NAME}.github.io/test2 sites.
• However, the repos/GitHub Pages with names that are the same as the HfLA website's pages (/join) or redirects (/cop) will result in not being able to preview those HfLA website pages. For example, if Website-Test-Org has a repo named "join" and then use the instructions to view the HfLA site using a fork of the repo, when trying to navigate to https://website-test-org.github.io/join, the result is the contents of the "join" repo and not the HfLA join webpage.

Make GitHub Pages Private?

• See if the forked repo's GitHub Pages website can be private view to prevent people searching for HfLA from seeing everybody's forked HfLA websites

Answer:

• Can only be private with an Enterprise plan
  

Can GitHub repo be renamed "{GITHUB HANDLE}.github.io/website"?

Answer:

• No, GitHub doesn't allow forward slashes in repo names

## Add/Edit Instructions No longer doing this because of this decision: #6219 (comment)
- [ ] Unpublish GitHub Pages
- [ ] How to republish if unpublished before

[ExperimentsInHonesty]

@JessicaLucindaCheng ok, so it can't be private, we still want to know if the rest works

[JessicaLucindaCheng]

@ExperimentsInHonesty

@JessicaLucindaCheng ok, so it can't be private, we still want to know if the rest works

Sorry, I didn't clearly label my findings. I have edited the comment (#6219 (comment)) with "Answer" headers for clarity. Let me know if I missed something that needs to still be addressed.

[ExperimentsInHonesty]

@JessicaLucindaCheng Thank you for the work that you put into this.

We have made a decision not to do this for the following reasons

1. We are concerned that old versions of our site will remain out on repos and could eventually show up in search results, lowering the quality of results people get when looking for HfLA
2. It's quite complicated to follow the instructions, and would require the merge team to then support people who don't understand the instructions, increasing the burden on the merge team
3. We had thought we needed it for the wins page work, but team member who have to do a pr to their own repo of the website to test, can then just pull down the site from their own repo and see it in docker.

Do you want to write a DR for this to close this issue out?

[JessicaLucindaCheng]

@ExperimentsInHonesty

@JessicaLucindaCheng Thank you for the work that you put into this.

We have made a decision not to do this for the following reasons

1. We are concerned that old versions of our site will remain out on repos and could eventually show up in search results, lowering the quality of results people get when looking for HfLA
2. It's quite complicated to follow the instructions, and would require the merge team to then support people who don't understand the instructions, increasing the burden on the merge team
3. We had thought we needed it for the wins page work, but team member who have to do a pr to their own repo of the website to test, can then just pull down the site from their own repo and see it in docker.

Do you want to write a DR for this to close this issue out?

• Yes.

[ExperimentsInHonesty]

@JessicaLucindaCheng

Yes, We should have a DR for this written. Are you going to write it, or do you want someone else to write it?

[JessicaLucindaCheng]

@ExperimentsInHonesty

@JessicaLucindaCheng

Yes, We should have a DR for this written. Are you going to write it, or do you want someone else to write it?

Yes, I will write it. Should I wait until the wiki repo is ready before writing it? Or should I just go ahead and write it and submit a pr in the wiki repo that will be merged later?

[ExperimentsInHonesty]

@JessicaLucindaCheng , go ahead and write it.

[JessicaLucindaCheng]

Issue Progress

• Progress: I have completed writing the decision record and this is the pr: Created a decision record for not using a forked repo's GitHub pages … website-wiki#17. Also, it has been merged.
• Blockers: None
• Availability: N/A
• ETA: N/A