Make the PHAR "website" a little more fancy

[jrfnl]

The PHAR files get published with each release on the releases page, but they also are available via a permanent address: https://phars.phpcodesniffer.com/ with historic phars available for download in the https://phars.phpcodesniffer.com/phars/ subdirectory.

This subdomain is managed via the gh-pages branch in this repo and is currently very plain.

It would be nice to make the "homepage" look a little more fancy/professional than the current quick & dirty:

It would also be nice if the phars subdirectory would contain an (automated) listing of all historic PHAR files available (instead of the 404 it currently displays).

[mbabker]

I'm not a GitHub Pages user, but https://github.com/marketplace/actions/github-pages-directory-listing looks like it might be able to give something for the directory listing bit (at least as a first step so the subdirectory has an index page, whether it's "good" long term is subjective).

[jrfnl]

@mbabker Nice suggestion.

The GH Pages site is currently managed via a gh-pages branch, not via a workflow (historic reasons), so that setup would need to change for that action runner to be able to work I think.

The GH Pages site currently also explicitly does not use Jekyll. Not sure if that would be needed for that action, but also something to maybe have a think about.

P.S.: and yes, I do have some experience with GH Pages sites, both via the historic setup as well as creating them via the new workflow setup, so happy to discuss options.

[benno5020]

@jrfnl Hi! Is this issue still relevant? If so, I'd be happy to help.
A few quick questions:

• What’s the reason for having these pages? Is it primarily because they’re easier to search than GitHub’s Releases page?
• What do you mean by “fancy”? A more "styled" look compared to default user-agent styles? Something like this, perhaps?
• Am I correct in understanding that you're currently updating the files in the gh-pages branch manually?

  PHP_CodeSniffer/.github/release-checklist.md

  Line 101 in 368817d

  - Update the `gh-pages` branch:

One quick option might be to leave everything as-is but add a new phars.html that queries
https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/contents/phars?ref=gh-pages
and formats the response. But that feels a bit odd since we already know what should be on the page. I'd also image that, ideally, the page should be easily scrapable - so using JavaScript to load the main content might not be a great idea.

Maybe the better approach is to write a script that queries all pages from:
https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/releases,
generates a static page, and you can then push the output to gh-pages after every release?

Please let me know what you think :)

Bernhard

[jrfnl]

Hi @benno5020, good questions.

Is this issue still relevant? If so, I'd be happy to help.

Yes, the issue is still relevant and your help is welcome.

• What’s the reason for having these pages? Is it primarily because they’re easier to search than GitHub’s Releases page?

No, the reason is primarily as a release channel for the PHAR files used by PHIVE - also see the https://phars.phpcodesniffer.com/phars/phive.xml file.
The secondary reason is to provide stable URLs [*] for people who use cURL/wget to download the latest PHAR files.

[*] Yes, I realize that GH offers a stable "latest" URL, but this project has moved multiple times now, which has meant that that "stable" URL has already been broken a couple of times. And while there are no plans to move (again) at this time, I prefer to have a future-proof stable URL available, which is what is achieved via the https://phars.phpcodesniffer.com subdomain.

• What do you mean by “fancy”? A more "styled" look compared to default user-agent styles?

Yes, a little more styled look, but possible also a little more information on the "root" homepage, maybe something like a one paragraph mini-introduction to the project, including links to the repo and to the documentation in the wiki.

Something like this, perhaps?

Something like that would definitely already be an improvement for the <phars.phpcodesniffer.com/phars/> index page (which is currently a 404).

• Am I correct in understanding that you're currently updating the files in the gh-pages branch manually?

Correct. The PHAR files for PHIVE should be available before the release is published and the emails about the release are send out and as the PHIVE releases also need the asc files (which are also created manually and won't be available anywhere, but on my local computer until the release is published, updating the gh-pages branch manually is, unfortunately, the only stable option for now.

One quick option might be to leave everything as-is but add a new phars.html that queries https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/contents/phars?ref=gh-pages and formats the response. But that feels a bit odd since we already know what should be on the page. I'd also image that, ideally, the page should be easily scrapable - so using JavaScript to load the main content might not be a great idea.

Maybe the better approach is to write a script that queries all pages from: https://api.github.com/repos/PHPCSStandards/PHP_CodeSniffer/releases, generates a static page, and you can then push the output to gh-pages after every release?

Except that that would be too late, which is why the release process, including the manual update of the gh-pages branch - at this time - is not really open for change.

While the manual update of the gh-pages branch feels unavoidable at this time, it does not mean that we couldn't adjust the workflow from auto-deploy via the "old" GH Pages mechanism to a custom deploy workflow, providing that would add value.

Does this help clarify things a little ?

[benno5020]

Yes, thank you for the clarifications!

Here's what I came up with. I think the design is still a little bland but I guess it's more appealing than user agent styles. The list of all phars is currently generated by a php script that reads the phars directory but I guess one could just as well maintain it manually. What do you think?

[jrfnl]

@benno5020 Definitely looks better - more "fancy" 😉 - than it currently is.

I suppose it would be straight-forward to add the PHAR file size and modified date to the listing ? I can imagine, people might find that information useful.

And if a script would be used anyway (and the workflow changed to run the script and deploy the preprocessed files), I suppose it would also be possible to auto-generate the phive.xml file ?

Note: don't feel obliged to look into this, I'm perfectly happy with doing iterative improvements and the screenshots you posted above would already be a huge improvement compared to what is there now.

[jrfnl]

Closing this as actioned. There is a follow up issue open for the next steps: #1167