Project

General

Profile

Actions

Bug #5902

closed

manuals only built for "master" and published in a folder "latest"

Added by laforge about 1 year ago. Updated 11 months ago.

Status:
Resolved
Priority:
Normal
Assignee:
Target version:
-
Start date:
02/10/2023
Due date:
% Done:

100%

Spec Reference:

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
Actions #1

Updated by osmith 12 months 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.

Actions #2

Updated by neels 12 months 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?

Actions #3

Updated by laforge 12 months 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?

Actions #4

Updated by osmith 12 months 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

Actions #5

Updated by osmith 12 months 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
Actions #6

Updated by osmith 12 months 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?

nginx config

Actions #7

Updated by osmith 12 months ago

  • Assignee changed from osmith to laforge
Actions #8

Updated by laforge 12 months 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.

Actions #9

Updated by osmith 12 months 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.

lighttpd config

Actions #10

Updated by osmith 11 months 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

Actions #11

Updated by osmith 11 months ago

  • Status changed from In Progress to Resolved
  • % Done changed from 90 to 100
Actions

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)