Bug #5902
closedmanuals only built for "master" and published in a folder "latest"
100%
Description
We initially started to put nightly builds of the osmo-* user manuals at https://ftp.osmocom.org/docs/latest/
Then we started to have "latest" debian packages which actually are the latest tagged releases, and not the "nightly" builds.
This is confusing, but probably hard to resolve by now.
What's even more strange is that we don't have builds of user manuals for the last tagged versions, or even for any earlier tagged versions.
Ideally we would build the user manuals for every tag in the repo, and have the PDF renderings for that version available somewhere on {ftp,downloads}.osmocom.org
There's of course a risk that some ancient release will fial to build its manual on a modern debian, but I guess we can deal with that by explicitly blacklisting "known broken" tags.
Checklist
- osmo-gsm-manuals: Change upload path to project/master/: write patch
- osmo-gsm-manuals: Change upload path to project/master/: merge
- pysim: adjust to publish manuals to project/master
- wait until all manuals were published to new directory structure
- set up nginx redirects for all existing manuals
- delete the "latest" directory
- generate manuals for previous releases: write script & jenkins job
Updated by osmith about 1 year ago
I would go with this directory structure:
docs/
osmo-hlr/
master/
osmohlr-usermanual.pdf
osmohlr-vty-reference.pdf
1.6.1/
osmohlr-usermanual.pdf
osmohlr-vty-reference.pdf
And for docs/latest, I'd suggest making redirects in the nginx config so e.g. docs/latest/osmohlr-usermanual.pdf points to docs/osmo-hlr/master/osmohlr-usermanual.pdf. Then delete the latest directory.
EDIT: docs/latest could also be redirected to docs, in case somebody has that as bookmark.
Updated by neels about 1 year ago
And for docs/latest, I'd suggest making redirects in the nginx config so e.g. docs/latest/osmohlr-usermanual.pdf points to docs/osmo-hlr/master/osmohlr-usermanual.pdf. Then delete the latest directory.
makes sense for "backwards compat", but from the naming, "latest" should rather point to the latest release?
Updated by laforge about 1 year ago
On Fri, Mar 03, 2023 at 12:43:27AM +0000, neels wrote:
Issue #5902 has been updated by neels.
And for docs/latest, I'd suggest making redirects in the nginx config so e.g. docs/latest/osmohlr-usermanual.pdf points to docs/osmo-hlr/master/osmohlr-usermanual.pdf. Then delete the latest directory.
makes sense for "backwards compat", but from the naming, "latest" should rather point to the latest release?
Now I'm confused. This ticket exists to create a backwars-compatible work-around for the situation we've had
form any years:
We initially started to put nightly builds of the osmo-* user manuals at https://ftp.osmocom.org/docs/latest/
Then we started to have "latest" debian packages which actually are the latest tagged releases, and not the "nightly" builds.
So how is your comment improving the situation, other than stating "we should break compatibility and not
bother at all with people following old links?
Updated by osmith about 1 year ago
- Checklist item osmo-gsm-manuals: Change upload path to project/master/: write patch added
- Checklist item osmo-gsm-manuals: Change upload path to project/master/: merge added
- Checklist item pysim: adjust to publish manuals to project/master added
- Checklist item wait until all manuals were published to new directory structure added
- Checklist item set up nginx redirects for all existing manuals added
- Checklist item delete the "latest" directory added
- Checklist item generate manuals for previous releases: write script & jenkins job added
- Status changed from New to In Progress
- % Done changed from 0 to 30
Neels, FYI the "latest" name would not be visible anymore in the directory listing or in the URL. There would only be redirects from latest to master, the same file that the user would get with the previous URL.
First patch to publish manuals to $project/master from now on:
https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/31688/1
Updated by osmith about 1 year ago
- Checklist item osmo-gsm-manuals: Change upload path to project/master/: merge set to Done
- Checklist item pysim: adjust to publish manuals to project/master set to Done
pysim html docs: https://gerrit.osmocom.org/c/pysim/+/31718
Updated by osmith about 1 year ago
- Checklist item wait until all manuals were published to new directory structure set to Done
- % Done changed from 30 to 40
laforge: here are the redirect rules (untested), can you apply them to nginx config of the server and assign the issue back to me?
Updated by laforge about 1 year ago
- Assignee changed from laforge to osmith
It's not nginx (as it doesn't have anyway nearly as sophisticated directory indexing as we want, with sort-by-date), but lighttpd.
I've added your ssh key for root@2a01:4f8:201:344a::1:2 so you can change the configs of the system-installed (debian) lighttpd in /etc/lighttpd/
There's an etckeeper so you can keep track of modifications and/or revert back.
Updated by osmith about 1 year ago
- Checklist item set up nginx redirects for all existing manuals set to Done
- Checklist item delete the "latest" directory set to Done
- % Done changed from 40 to 60
laforge wrote in #note-8:
It's not nginx (as it doesn't have anyway nearly as sophisticated directory indexing as we want, with sort-by-date), but lighttpd.
I've added your ssh key for root@2a01:4f8:201:344a::1:2 so you can change the configs of the system-installed (debian) lighttpd in /etc/lighttpd/
There's an etckeeper so you can keep track of modifications and/or revert back.
Done.
Updated by osmith about 1 year ago
- Checklist item generate manuals for previous releases: write script & jenkins job set to Done
- % Done changed from 60 to 90
Manuals for previous releases generated:
https://downloads.osmocom.org/docs/
Script and jenkins job:
https://gerrit.osmocom.org/c/osmo-ci/+/32016
Updated by osmith about 1 year ago
- Status changed from In Progress to Resolved
- % Done changed from 90 to 100
