On Tuesday, 26 June 2018 at 17:12:37 UTC, H. S. Teoh wrote:
On Tue, Jun 26, 2018 at 12:54:11PM -0400, Steven Schveighoffer
via Digitalmars-d wrote: [...]
1. The dlang.org repository is backwards -- master generates
the docs for the default dlang.org. I've brought this up
before, still don't understand why we don't use stable for the
latest dlang.org.
Probably because we want to keep phobos-prerelease up-to-date
with git master?
FWIW the docs in the release archives are built from stable.
The reason is that both stable _and_ master are built on
dlang.org, so historically no one was interested in doing release
management for the docs.
The only sane way to do this IMO is to make the dlang.org
makefiles generate multiple versions of the docs, thereby
acting as the authoritative source for all dlang.org pages.
It already takes 20 minutes to do a full build of all dlang.org
HTML pages.
Doing it for old versions is a REALLY bad idea as you are
susceptible to
- more random failures (e.g. DUB registry being down)
- it will take hours for each build
- it won't be possible to do it in a CI for each PR due to the
large time required, which means the deployment could be broken
without us knowing
- resources might be offline or change (e.g. currently it fetches
the RSS from the DBlog for the frontpage indexes, this already
broke the build a few times)
- building all versions will fail due to newer dependencies or
OS-level changes (e.g. -fPIC, glibc changes, ...)
This means released specs need to be archived separately (e.g.,
by copying to spec/${version}/* and linking stuff there).
I just checked the versioned docs with the button on the upper
right of the page... it links to dlang.io, which IMO is a bad
idea, not because of dlang.io itself but because we're
basically relying on an external URL to contain what we assume
it might contain. IMO it's better to keep all versions of the
docs in a single repo (dlang.org) so that things can be
updated/refreshed from a single source, in keeping with SSOT.
Doing it that way then lets us do things like fix typos in
older docs without unnecessary complications.
Ehm the docarchives are simple a snapshot of each version (that's
why the "Improve this page" doesn't work or the "Version" button
says it's stable even though it's 2.076 (or there isn't even a
version button at all).
Anyhow, I'm pretty sure that we don't want to put all the HTML
files into the main dlang.org git repo. It's about 5 GB extracted.
The repo is here and part of the official D GitHub organization
https://github.com/dlang/docarchives.dlang.io
I don't see any problem of hosting it there, after all, the
content never changes.
There hasn't been much interest in it so far, so I doubt that
moving things will make this any better.
