search

gap-system / GapWWW

Source for the GAP website
https://www.gap-system.org
Other
11 stars 26 forks source link

Decide where/how manuals for GAP and packages are hosted in the future #223

Open fingolfin opened 3 years ago

fingolfin commented 3 years ago

Right now, all sources for the GAP website are in this repository, with one (?) major exceptions: the manuals for GAP and for the packages are not in here. This is so because they require a lot of storage; in particular all those PDFs add up (and binary files in general should better not be put into a git repository). In total I think it's something like 300 MB. And when we make a new release, new versions of those PDFs come in, and the .git dir will keep growing and growing, and git clone will get slower and slower...

For the HTML pages alone, I think it's not as bad; also they are text and git can deal with them and updates reasonably well.

Overall it really would be nice to have everything in one place; e.g. for backup purposes, but also because it potentially allow us to move to other hosting, perhaps even to GitHub Pages.

Several ways to deal with this come to mind:

  1. stop offering PDF files, only post instructions where to find them in the GAP release resp. how to access them elsewhere (but quite some people do seem to use the PDFs).
  2. Use git lfs to store them (see also the gitlab tutorial. Pro: avoid cluttering and growing the repository; con: people who want to interact with the GapWWW repo fully need to install git-lfs (but note that most package managers offer it, and installing it via download also is not that hard). Also, GitHub Pages does not immediately support it (see this issue -- but there are workarounds, also described in that issue)
  3. Upload the PDFs somewhere to https://files.gap-system.org -- but then this of course requires somebody who has SSH access to that machine (still doable, though)
  4. ... other options ... ???
fingolfin commented 3 years ago

Slightly related: issue #105

fingolfin commented 3 years ago

Another option I am now contemplating is to add another subdomain, say docs.gap-system.org, which for now could point at the same server in St Andrews, and then move all the manuals HTML and PDF alike) there. Then also move the ForumArchive (say to files.gap-system.org -- does anybody even care about this?).

Once this is done (and all links set up, and redirects configured from the old to the new URLs, we can then contemplate hosting the pure HTML parts elsewhere, even in GitHub Pages, which would have the great benefit that it's much easier for us to let many people access and edit it safely there. Of course the manuals then still would be "gone" during St Andrews outages (both scheduled ones, like today, and unscheduled ones). But at least the website as such and the latest release would be available. That said, GH pages has one drawback: it doesn't allow configuring 301 / 302 HTTP redirects, which would be really nice to have for at least some time, to migrate people from the old to the new URLs...

Another alternative would be to host it in TU Kaiserslautern (but then again people need accounts to SSH in for at least some maintenance actions -- of course we should try in any case to setup a regime where the website is updated by a GitHub Action, but one needs to be very careful with that in terms of security.

RussWoodroofe commented 3 years ago

I'm writing in support of moving documentation to a predictable location. I want to particularly point out that having a predictable translation from the location of local help files to an online URL would make it easier to share links to particular points in the documentation.

fingolfin commented 3 years ago

@RussWoodroofe Not sure I get your point: The current locations are also predictable and have been for years?

wilfwilson commented 3 years ago

This discussion in https://github.com/gap-system/ReleaseTools/issues/73 is related.