Giters

xmonad / xmonad-web

The xmonad.org website

Home Page:https://xmonad.org

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Update the website

TheMC47 opened this issue · comments

commented

This isn't an issue per se, but I changed a lot to the point a PR doesn't make sense (many conflicts, since I took #5 as my starting point).

Where are the changes?

The source is at https://github.com/TheMC47/xmonad-web/tree/master (so it can be easily deployed to GitHub pages). A preview is available at https://themc47.github.io/xmonad-web/index.html

What is changed

  • Cosmetics. I went with the style by https://github.com/tsier (in #5) and cleaned it up a bit
  • Hakyll, instead of plain HTML. I think it's more convenient, and we'd only need to edit markdown pages this way
  • I didn't change the content almost at all. I'm just trying to get the ball rolling. However, I removed some things (either I didn't reach them through browsing the website, all they're old/outdated like press.html)

What next?

  • I think we should include the tutorial from @slotThe in the Getting Started link or as the step-by-step guide here https://themc47.github.io/xmonad-web/documentation.html
  • The links to the wiki are kept as they are. We could relatively easily import the wiki to the website since it's just markdown.
  • The content needs to be reviewed and updated. I hope this is easier to do because of markdown. However, I think we should do this after deploying the cosmetic changes. That way we have our pipeline setup.
  • If we go through with this, I think we should rename the old gh-pages branch and move my master branch to gh-pages

I'm waiting for your feedback!

Notes
  • Hiding the menu in the header is broken (clicking the button doesn't bring back the menu)
commented

Looks good! Haven't looked at details, but it seems to get the ball rolling indeed. ♥
I agree that modernizing the look and updating content can be two separate steps.

Just one thing that I'd love to see: gh-pages branch with just the generated output, and master with the sources, with some GitHub Actions to build it automatically. I'll be happy to help here (but I should probably focus on finishing all the other stuff that I started to work on).

commented

This looks great! Thanks for working on this! Can't wait to see this live on xmonad.org!!

commented

Thanks for the feedback!

Just one thing that I'd love to see: gh-pages branch with just the generated output, and master with the sources, with some GitHub Actions to build it automatically. I'll be happy to help here (but I should probably focus on finishing all the other stuff that I started to work on).

That would be awesome. You could point me to some resources and I'll check the rest (this seemed good https://www.stackbuilders.com/news/dr-hakyll-create-a-github-page-with-hakyll-and-circleci)

commented

That would be awesome. You could point me to some resources and I'll check the rest (this seemed good https://www.stackbuilders.com/news/dr-hakyll-create-a-github-page-with-hakyll-and-circleci)

I think using git submodules is unnecessary and will probably only complicate matters. All we really need here is to have a github action running on push to master branch that builds the site into a subdirectory, commits that subdirectory and (force)pushes the result into the gh-pages branch, and then tell GH Pages to serve from that subdir of gh-pages branch (https://docs.github.com/en/github/working-with-github-pages/about-github-pages#publishing-sources-for-github-pages-sites). I suspect you already configured the latter on your repo, now we just need to automate the build and push.

commented

Oh my, 44 minutes for what Jekyll does in seconds. 🤦

(Sure, it's not that much of an issue because of the cache, but then, GitHub will remove any cache entries that have not been accessed in over 7 days., so if we rarely update the website, we will wait 45 minutes every time we do. Maybe it's still worth it, but the next time someone mentions Haskell builds are fucked up, remember that this is why they might be right.)

Anyway, some minor issues:

Also, where does https://github.com/TheMC47/xmonad-web/blob/master/.github/workflows/deploy-gh-pages.yaml#L39 come from? Not saying it's wrong, but I'd like to understand what it means.

commented

@TheMC47 Oh, and: sorry about being so negative! You did a lot of work and most of it is awesome. Just wanted to reply quickly on the remaining issues and couldn't help ranting about the builds, because as I've worked with Haskell a lot lately, they really do frustrate me greatly. :-/

commented

Thank you for the quick feedback!

  • the burger menu still doesn't work on mobile

sigh I forgot about that problem. I'll see if there's a solution that doesn't require js

  • drop the docs directory from master

👍

I don't know? I just kinda googled some stuff and just went with the first thing I saw. This is the first time writing GitHub actions, and now I see that the action is unnecessary

Also, where does https://github.com/TheMC47/xmonad-web/blob/master/.github/workflows/deploy-gh-pages.yaml#L39 come from? Not saying it's wrong, but I'd like to understand what it means.

It was in the example from the push action https://github.com/marketplace/actions/github-push. Apparently, that way GitHub links the commits to an account. I also found that it's referenced here actions/checkout#13 (comment)

@TheMC47 Oh, and: sorry about being so negative! You did a lot of work and most of it is awesome. Just wanted to reply quickly on the remaining issues and couldn't help ranting about the builds, because as I've worked with Haskell a lot lately, they really do frustrate me greatly. :-/

it's fine, really! I can understand the frustration. Thanks again for the quick feedback. I'll drop another comment after doing the changes

commented

I'm having problems pushing to the gh-pages branch without the external action... I'd need to create a personal access token, otherwise GitHub will not allow it (because it might cause recursive workflows). So I'm bringing the action back

commented

No, this is not about tokens at all:

https://github.com/TheMC47/xmonad-web/runs/2282218880?check_suite_focus=true

error: src refspec gh-pages does not match any
error: failed to push some refs to 'https://github.com/TheMC47/xmonad-web'

You just need to either git checkout -b gh-pages before the commit/push, or git push --force origin HEAD:gh-pages

(We might even wish to retain the gh-pages history by doing some git merge trickery but don't worry about it, I can do this later.)

commented

Also, where does https://github.com/TheMC47/xmonad-web/blob/master/.github/workflows/deploy-gh-pages.yaml#L39 come from? Not saying it's wrong, but I'd like to understand what it means.

It was in the example from the push action https://github.com/marketplace/actions/github-push. Apparently, that way GitHub links the commits to an account. I also found that it's referenced here actions/checkout#13 (comment)

Cool, didn't know about this. 👍

commented

This kinda reminds me of the GenerateManpages issue we're trying to escape. I can't see a gig and 45 minutes being particularly justified, especially if some other tool gets it down to a minute or so.

commented

These are all valid points. The good thing is, I didn't spend a lot of time working on hakyll; most of it went into pulling the pages from the website and improving and cleaning up the CSS. I'm optimistic we could easily migrate to another tool.

So now the question: what tool do you think is suitable?

commented

Hakyll is supposed to be modeled on jekyll, and @liskin said that should generate in a few seconds; can we try that? Alternately we try to figure out why hakyll is behaving so poorly, since it should be a relatively simple task (he says…) given the website is static and fairly simple.

commented

Hakyll is supposed to be modeled on jekyll

Perhaps it was initially, but Hakyll 4.0 is different from Jekyll. Hakyll is a DSL for building sites, whereas Jekyll is a configurable generator.

With that said, the only somewhat-complicated part of this website is videos — I'm not sure how to translate that into Jekyll.

Alternately we try to figure out why hakyll is behaving so poorly

It takes 40 minutes to compile, that's the only issue. The site itself builds in 20 seconds.

We could re-compile the site every 6 days to keep the caches, but that's a hack (and GitHub will disable such jobs after a few months if nothing is pushed to the repo).

commented

Ah, ok, that's why it was suggested to install it from debian. That might indeed be a possibility. (What's the build issue? Is it using pandoc behind the scenes? That would make it pretty much the same as the GenerateManpages issue.)

commented

Oh, I missed the suggestion to install from the repo. Sure, that'll do the trick!

Yes, Pandoc is about a third of the issue. But there's just a lot of transitive dependencies that take time to build.

commented

I build hakyll in a container every night

https://github.com/eyenx/docker-hakyll/actions

And the build is failing for me since a week, so looks like upstream problem.

commented

I build hakyll in a container every night

As this solves the problems while building the website, using hakyll is discouraging for anyone to contribute to the website ☹️ we're better off using something else.

But as said, the only "tricky" part is getting the videos page to generate, otherwise the rest should work as is

commented

Jekyll and its Liquid templating should work for the few videos just fine I think. :-)

commented

@eyenx > And the build is failing for me since a week, so looks like upstream problem.

The builder appears to install GHC 8.4.4 but then Cabal fails because of base 4.15, which should only be available in GHC 9.0. Please look into that, and if you find something has to change on Hakyll's side, please report it to us. We can't fix issues we aren't aware about ;)

commented

@eyenx > And the build is failing for me since a week, so looks like upstream problem.

The builder appears to install GHC 8.4.4 but then Cabal fails because of base 4.15, which should only be available in GHC 9.0. Please look into that, and if you find something has to change on Hakyll's side, please report it to us. We can't fix issues we aren't aware about ;)

Thx. Will do!

commented

Was able to fix it. by using

FROM haskell:8-buster
commented

Alright, I changed the website over to jekyll, which was a bit more work than I anticipated (but nothing too bad). The builds are really fast (around one minute without cached dependencies). I also fixed the problem with toggling the menu.

(Sorry for the noise, I had to try a couple of things with the GitHub actions till I found the problem)

commented

Do we actually need the action at all? GitHub Pages invokes Jekyll automatically.

commented

@liskin how would it know to do so? I removed the action, and it didn't update the website

maybe I'm missing something

commented

You'd need to configure the GitHub Pages branch back to master again, probably…

commented

That seems to work, thanks!

commented

Sounds like we're ready to go?

commented

I think we are! If there are no objections, I'd need write access to the repository, so I can push my master branch into the master branch here, set it as the default branch, and add the CNAME file. Maybe also rename the old gh-pages branch into old-website. By this point, I think it makes little sense to create a PR.

Or somebody else with sufficient privileges can do it

commented

Can't you just create a PR from your fork into master?

commented

The master branch doesn't exist, and I've based my branch off of tsier's branch (#5), because they should get credit for the design. The branches diverged, not sure what's the added value of trying to consolidate the histories

oh and there is no master branch here

commented

I will try and give you permissions in the next few hours.

commented

The branches diverged, not sure what's the added value of trying to consolidate the histories

Doing a git merge shouldn't be that difficult though? It's what I was planning to do anyway. If the branches diverged, might be a good idea to check if nothing is missing from the new website, and what better tool than git do we have? :-)

commented

I don't have permissions to give you rights anyway... :-P sorry @TheMC47

commented

If the branches diverged, might be a good idea to check if nothing is missing from the new website

There are files in the repository that aren't reachable on the website, and I didn't bother to include those. Anyway, I rebased on top of the gh-pages branch

I don't have permissions to give you rights anyway... :-P sorry @TheMC47

Thanks for checking!

commented
commented

Sorry, got it. @TheMC47 you should have push access now.

commented

Thank you @geekosaur, and sorry for the trouble! After I rebased, I don't need the push access anymore (I was worried that it would take a lot of time to rebase, but there were only around 20 commits). I opened a PR (#20) for that. I'll also squash the commits, there's a lot of noise

commented

And we're live 🎉 thank you everyone for the feedback