search

philipwalton / flexbugs

A community-curated list of flexbox issues and cross-browser workarounds for them.
MIT License
13.63k stars 495 forks source link

Hosting examples on GitHub pages #276

Closed akaustav closed 4 years ago

akaustav commented 4 years ago

Fixes #274. Code reviews welcomed.

akaustav commented 4 years ago

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

Before (from README.md on GitHub):

image

After (from GitHub pages):

image

philipwalton commented 4 years ago

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

A couple of initial comments:

akaustav commented 4 years ago

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 commented 4 years ago

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

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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

... 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):

image

akaustav commented 4 years ago

@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:

image

akaustav commented 4 years ago

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

akaustav commented 4 years ago

@philipwalton So, do you have any thoughts/opinions on the new changes in this PR? Am I clear to s/akaustav/philipwalton/g now?

philipwalton commented 4 years ago

Yes, I think we're almost good to merge. The main thing I'd like to make sure happens before merging is that we get the right vendor prefixes in case folks are testing these demos in the browsers we say have bugs.

mreinstein commented 4 years ago

this could help with the prefixing https://autoprefixer.github.io/

akaustav commented 4 years ago

@philipwalton Please review the latest changes and let me know if I can run s/akaustav/philipwalton/g now.

philipwalton commented 4 years ago

This looks good to me. Thank you!

akaustav commented 4 years ago

@philipwalton I have executed s/akaustav/philipwalton/g on this PR. Please review. If you'd like to do the honors, this PR is ready to be merged now. Or you could give me the necessary access, and I can change the following settings after merging the PR. After testing, I can open similar PR(s) (directly on this repo, or via a fork) to create the HTML files for the 16 remaining flexbugs and their workarounds.

Steps after merging

After merging, please perform the following steps in your GitHub repository:

  1. Navigate to https://github.com/philipwalton/flexbugs/settings.
  2. Scroll down to the GitHub Pages section.
  3. Set the following values:
    1. Source: master branch /docs folder.
    2. Theme Chooser: Slate theme - Feel free to choose any other theme.
    3. Custom domain: [blank]. Feel free to set a custom domain if you'd like - pretty sure we need to change the URL in README.md files if you decide to use a custom domain.
    4. Enforce HTTPS: Checked and Disabled. Says - required for your site because you are using the default domain.

After these changes, your screen should look similar to the following screenshot:

image

philipwalton commented 4 years ago

@akaustav I can definitely give you access (I'm very happy with what you've done so far and the thoughtfulness you've put into your changes). How would you feel about holding off on merging this though until after the rest of the HTML updates?

If not wanting to wait for a back and forth from me. I can give you access now and then you can make the changes needed whenever you have time. How does that sound?

akaustav commented 4 years ago

@philipwalton Sounds good to me. Now that we have an agreement on how one example should be done, I can replicate the same for the remainder of the examples in my fork. But here are some problems which I foresee:

I'll try updating here when I am ready to merge for you to review once before merging, I guess. Feel free to give me access to merge the PR when it is ready.

Side note: I noticed that there are 79 open issues on this repository - oldest one dating back to Jan, 2015. I replied to issue #281 this morning - which was closed quickly. While responding to that issue, I noticed that flexbug 12.1.a (and possibly others) is no longer reproducible in IE11 - example comment here. Do you need help to close out some of those long standing issues?

philipwalton commented 4 years ago

It will be difficult to test with the s/akaustav/philipwalton/g. I will probably need to revert that commit and run that same commit at the end after testing all other examples.

SGTM

Unless you have an alternative approach, it might be beneficial if I had debug view access to your pens on CodePen instead of cloning all your pens.

Hmmm, I just tried and it doesn't look like there's any way to grant other users access rights. If you know of a way I'd be happy to do that though.

I'll try updating here when I am ready to merge for you to review once before merging, I guess. Feel free to give me access to merge the PR when it is ready.

Sent you an invite earlier this morning :)

Side note: I noticed that there are 79 open issues on this repository - oldest one dating back to Jan, 2015. I replied to issue #281 this morning - which was closed quickly. While responding to that issue, I noticed that flexbug 12.1.a (and possibly others) is no longer reproducible in IE11 - example comment here. Do you need help to close out some of those long standing issues?

Yes, I would love help. I essentially have zero time to maintain this repo, and I would love it if more people from the community got involved. I should probably be more proactive about seeking external contributors (I think it would make sense to do that once this PR lands).

akaustav commented 4 years ago

@philipwalton: I have s/philipwalton/akaustav/g temporarily.

Hmmm, I just tried and it doesn't look like there's any way to grant other users access rights. If you know of a way I'd be happy to do that though.

No worries - I will continue to clone your pens for now. Meanwhile, looks like there are more features like Collab Mode and Professor Mode in CodePen Pro for Individuals or Teams which might allow to share pens without redundancy. But, I do NOT think it is worth spending money just for this feature.

Sent you an invite earlier this morning :)

My apologies. I did not realize that you had granted me collaborator access on this repository. I have accepted the access and I can see the "Merge pull request" button now - thanks for that. I am working to include all other flexbugs into my PR at the moment. Rest assured that I will NOT merge until all 17 of them are ready.

Side question: Which merge option do you prefer?

  1. Create a merge commit (default)
  2. Squash and merge
  3. Rebase and merge

On a related note, before I merge my PR, I am also thinking of creating a tag (named, let's say - codepen) from the latest commit on the master branch of this repository, as a backup - just in case we want to refer the original code in CodePen in the future. However, there is no point of this effort if you are planning on deleting your pens on CodePen. Any thoughts?

Yes, I would love help.

I will gladly try helping whenever time permits.

philipwalton commented 4 years ago

Side question: Which merge option do you prefer?

I prefer a merge commit myself, though I don't care if you prefer a different strategy and want to use the GitHub UI instead of manually squashing/rebasing superfluous commits.

Personally I do all my squashing/rebasing manually, but like I said, I'm open to whatever is easiest for you.

However, there is no point of this effort if you are planning on deleting your pens on CodePen. Any thoughts?

I don't think I'll delete them because I imagine some people might be linking directly to them on the web, and there's no point in breaking those links.

akaustav commented 4 years ago

@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 commented 4 years ago

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

philipwalton commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

akaustav commented 4 years ago

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):

@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 commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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

akaustav commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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

akaustav commented 4 years ago

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

philipwalton commented 4 years ago

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