Hosting examples on GitHub pages

[akaustav]

Fixes #274. Code reviews welcomed.

[akaustav]

See the working example for Flexbug#2 in GitHub pages here: https://akaustav.github.io/flexbugs/#flexbug-2

Before (from README.md on GitHub):

After (from GitHub pages):

[philipwalton]

Hey @akaustav, thanks for taking this on, and sorry for the slow reply!

A couple of initial comments:

• I think it's OK to have a gh-pages version of the README (especially if it's not being manually maintained by you), but my concern is existing links on the internet will fragment. I'd prefer if there was one clear place to link to, and since GitHub READMEs don't support redirects (as far as I know), then I'd prefer if the current README continues to be the main landing page.
• One of the nice things about CodePen was that it allowed people to easily play with the values and see the results. With GitHub pages you can see the values, but you can't easily modify them yourself. Have you considered something like Glitch? It might be just as easy to maintain a single Glitch repo with all the demos in separate folders.

[akaustav]

Hi @philipwalton,
My comments are inline:

I think it's OK to have a gh-pages version of the README ...

• I only created a GitHub pages version because it was suggested by @mreinstein (see comment) and you seemed open to the idea (your comment).

... (especially if it's not being manually maintained by you), ...

• I can confirm that I am NOT manually maintaining the GitHub pages hosted at https://akaustav.github.io/flexbugs. It was created automatically by the existing README.md. I followed this straightforward tutorial. This commit contains the auto-generated one-liner code change which enabled GitHub pages on my fork.

... but my concern is existing links on the internet will fragment.

• Just for the sake of clarity, if my PR is merged, I can assure you that the final GitHub pages URL will probably read https://philipwalton.github.io/flexbugs and not https://akaustav.github.io/flexbugs, if that is what you are concerned about. Having said that, the existing README.md is still necessary for that gh-pages homepage to exist. So, existing links on internet should not break (at-least not yet 😉).

I'd prefer if there was one clear place to link to, and since GitHub READMEs don't support redirects (as far as I know), then I'd prefer if the current README continues to be the main landing page.

• The real reason for gh-pages is hosting the static HTML files containing the bug and it's workaround. The current README can (and will) continue to be the main landing page. The GitHub pages homepage is merely a side-effect. You can treat it as an auto-generated supplement, if you want to treat it that way. People can still continue to read the description of the bug and it's workaround in the README.md. If you are still concerned, we can try putting up an alternate homepage on gh-pages - something which does NOT reference the README.md file - pretty sure I will find some solutions if I Google-fu.

One of the nice things about CodePen was that it allowed people to easily play with the values and see the results. With GitHub pages you can see the values, but you can't easily modify them yourself.

• It does not have to be GitHub pages. It can technically be a bunch of static html or hosted on a service which supports older browsers such as IE 9, 10 and 11 without showing an error message.

Have you considered something like Glitch? It might be just as easy to maintain a single Glitch repo with all the demos in separate folders.

• I have heard about Glitch, but not tried it myself yet. But I can certainly give that a shot as long as it supports older browsers where these bugs are prominently reproducible. Or perhaps add onto something which you might have already tried?

[philipwalton]

Just for the sake of clarity, if my PR is merged, I can assure you that the final GitHub pages URL will probably read https://philipwalton.github.io/flexbugs and not https://akaustav.github.io/flexbugs, if that is what you are concerned about.

I was not concerned about that, I was concerned that an existing link on the internet (e.g. https://github.com/philipwalton/flexbugs/#flexbug-9) would no longer go to a description of that bug. Based on your response, it sounds like the README file will stay as currently structured, which is great.

My other concern is that there'd start to become two URLs for the same bug, e.g.:

• https://github.com/philipwalton/flexbugs/#flexbug-9
• https://philipwalton.github.io/flexbugs/#flexbug-9

I think this is a problem because if then (in the future) we decide to move off of GitHub pages, then the link in the second bullet above would break. My preference is if the README continues to be the only "landing" page for the list of links, but I think it's fine if where the demos are hosted changes from time to time (hopefully not too much).

I don't have a strong preference between GitHub pages and Glitch, but if we land on using GitHub pages I think I'd prefer that the index page not be just another version of the README. Do you know if that's possible? If it can just link back to the README or display a table of contents for each of the demos that would be my preference.

[mreinstein]

pardon my ignorance, but isn't glitch another remote hosted service, like codepen? If that's the case, we're kind of at their mercy to continue supporting ie on their site right?

[philipwalton]

@mreinstein the part of CodePen that no longer supports IE 11 is their interactive viewer/editor. I was thinking we could use Glitch purely to host the demos, but I guess that's not really much different that using CodePen's debug view, e.g. here's Flexbug 1.1.a in debug mode (which works fine in IE 11):
https://cdpn.io/philipwalton/debug/MYbrrr/xJkjOnLWxXQM

I suppose another options would be to just link to both the interactive CodePen view and the debug view (for IE 11). What do people think of that?

[mreinstein]

Thanks for clarifying!

I'm hopeful as time progresses, the number of active flexbugs across browsers will continue to drop. Ideally at some point all that's left is ie related issues.

Assuming that happens, I think the biggest problem to solve is how to make this content viewable for a long time.

Being able to view these bugs in pages that still work in old browsers, and not having them hosted on an external resource are 2 things I think help preserve the viewability of this content. For me, the inability to live modify examples while viewing ie is an acceptable tradeoff.

[akaustav]

... e.g. here's Flexbug 1.1.a in debug mode (which works fine in IE 11):
https://cdpn.io/philipwalton/debug/MYbrrr/xJkjOnLWxXQM. I suppose another options would be to just link to both the interactive CodePen view and the debug view (for IE 11). What do people think of that?

@philipwalton - CodePen's debug view requires you to create accounts - and cannot be viewed anonymously. In one of the proposed solutions on issue #274, I mentioned to do the debug mode after creating an account/logging into CodePen. I see the following when I visit the above URL anonymously (in Chrome Incognito mode):

[akaustav]

@philipwalton / @mreinstein:
Glitch doesn't support Internet Explorer yet
When I try opening Glitch in IE11 on my Windows 10 laptop, I see this message:

[akaustav]

@philipwalton Now that we have established that codepen and Glitch might not work for rendering these bug examples and workarounds on Internet Explorer (because these websites have limited or no support for Internet Explorer), I have made the following changes in order to proceed with hosting on GitHub pages:

1. The main documentation stays in README.md. There are no secondary documentation on GitHub pages - see: https://akaustav.github.io/flexbugs.
2. All content inside the src folder have been moved into the docs folder.
3. GitHub pages now uses contents of the docs folder instead of the contents of the root folder.
4. For referencing source code on GitHub, we can use relative URLs.
5. For referencing rendered output on GitHub pages, we will need to use absolute URLs.

Once you confirm that these changes satisfy your requirements, I can change all instances of akaustav to philipwalton on this PR.

[philipwalton]

Yes, that sounds good to me. I agree that since CodePen debug mode still requires an account, it's not a good solution.

Everything looks good so far, I commented on a few minor things, but I think this direction is the right way to go, so thanks again for working on it!

[akaustav]

@philipwalton: I apologize, it took longer than I anticipated, but I have finally converted all 17 example bugs and their workarounds into gh-pages. Do you wish to take a final look before I merge this PR into the master branch?

To Do

• @akaustav created a tag called codepen - just in case we wish to refer back to the version of README.md which contained links to codepen.io
• @philipwalton to review all changes to this PR since last review and re-approve this PR
• @philipwalton to preview the corresponding README.md in my fork
• @akaustav to fix any issues which @philipwalton finds
• @akaustav to run s/akaustav/philipwalton/g
• @akaustav / @philipwalton to merge this PR
• @philipwalton to enable GitHub pages within repository Settings - @akaustav does NOT have access to the Settings tab yet.

[akaustav]

@philipwalton, need your help with this. Please advise.

[philipwalton]

Hey @akaustav, thanks! I've blocked out some time to take a look at this tomorrow. I'll get back to you after that.

[philipwalton]

I went through a few of the demos (randomly) and they all look good. I didn't notice anything that is different from the existing demos, so I think it's fine to move forward. If there's anything small that's incorrect, we can always fix it in the future (I'll keep my CodePen demos up for a while).

Also, feel free to add your name to the repo as a maintainer. You deserve credit for all the work you've put into this!

@philipwalton to enable GitHub pages within repository Settings - @akaustav does NOT have access to the Settings tab yet.

Hmm, not sure if that's a permission I can give you (it doesn't look like there's a higher role than "collaborator" for personal repos), but happy to make the change myself.

[mreinstein]

@akaustav thank you so much for all of this hard work! People like you are what make open source awesome to work with! :)

[akaustav]

I went through a few of the demos (randomly) and they all look good. I didn't notice anything that is different from the existing demos, so I think it's fine to move forward. If there's anything small that's incorrect, we can always fix it in the future (I'll keep my CodePen demos up for a while).

Thanks for reviewing this PR and the demo.
I have done the s/akaustav/philipwalton/g now.

Also, feel free to add your name to the repo as a maintainer. You deserve credit for all the work you've put into this!

How do I add myself as a repo maintainer?

Hmm, not sure if that's a permission I can give you (it doesn't look like there's a higher role than "collaborator" for personal repos), but happy to make the change myself.

I just read thru the GitHub docs around Permission levels for a user account repository. I'll let you decide what the best course of action is. The following rules apply to this repository owned by your user account (rules differ for repos belonging to organizations/teams/enterprise):

• There are two permissions:
  • owner
  • collaborators
• There is only ONE owner (However, there is an option to transfer ownership or convert a user account to an organization account).
• There can be multiple collaborators.
• Only the owner can view and change the settings for the repo.

@akaustav thank you so much for all of this hard work! People like you are what make open source awesome to work with! :)

I appreciate the kind words, @philipwalton.
You have been a great mentor and guide yourself - helping me with most of the decisions on this PR.

[philipwalton]

How do I add myself as a repo maintainer?

I just meant feel free to list yourself here (if you're comfortable with that):
https://github.com/philipwalton/flexbugs/#acknowledgments

There is only ONE owner (However, there is an option to transfer ownership or convert a user account to an organization account).

Hmmm, if there can only be one owner, then I'll probably keep it as is right now. But if it becomes the case that you're constantly needing to ping me for approvals to change settings like this, then I'll certainly consider transferring at that point.

[akaustav]

@philipwalton Also, do you think it is a good idea to keep a backup of the original README.md file with links to codepen.io (perhaps inside a backup folder - like: backup/README.original.md)? Or does the codepen tag suffice?

[philipwalton]

I think it's fine to just keep what's already in the git history.

[akaustav]

@philipwalton Added myself to list of maintainers. If you don't mind quickly checking if the change is fine, then I can go ahead and merge this PR.

[gregwhitworth]

ASIDE @akaustav thanks for tackling this stuff. I've been slammed with other work and unfortunately this has taken a back seat.

As always, @philipwalton thanks for keeping the lights on :)

[philipwalton]

LGTM, thanks so much! Feel free to merge yourself if you're ready.

[akaustav]

Alright, @philipwalton, I am merging this PR now.
Refer to the comment above about how to enable GitHub pages in this repo.

[philipwalton]

OK, I turned on GitHub Pages. Everything seems to be working great! Thanks again @akaustav!