Bug 30532 - Rework release process for documentation
Rework release process for documentation
Status: NEW
Product: UCS manual
Classification: Unclassified
Component: General
unspecified
All Linux
: P5 normal (vote)
: ---
Assigned To: Docu maintainers
https://hutten.knut.univention.de/med...
:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2013-02-21 09:12 CET by Philipp Hahn
Modified: 2018-09-20 07:48 CEST (History)
1 user (show)

See Also:
What kind of report is it?: Development Internal
What type of bug is this?: ---
Who will be affected by this bug?: ---
How will those affected feel about the bug?: ---
User Pain:
Enterprise Customer affected?:
School Customer affected?:
ISV affected?:
Waiting Support:
Ticket number:
Bug group (optional): Further conceptual development
Max CVSS v3 score:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Philipp Hahn univentionstaff 2013-02-21 09:12:13 CET
Currently the documentation is build on omar or locally by each user.
The Makefile "exports" the generated to the local ../webroot/ directory, where all documentations (UCS, UCC, Extended, UCS@school, Dev) are staged.

Calling the ./sync.sh script there transfers _all_ files from there to omar (unless an argument is explicitly passed to filter the file names).

This is error prone, since it might overwrite other documentations (not yet QAed or old versions from a previous local build). So currently the local webroot/ directory should be cleared before a new manual is prepared.

Some ideas for solving this issue:

1. Don't install to webroot by default, but rename the current "export" to "install" (for consistency with Makefile standard naming scheme). This should not be called by default (all), but only after the QA phase. The destination directory should be changeable to allow local test installations (by default) , but also final installations after QA.

2. Jenkins currently already builds all documentations, which guarantees a consistent build tool chain. Currently a single job builds all documentations. Which could be split into different jobs; one for each document.
Builds can be tagged as stable, which are then stored forever. A second jobs can be triggered manually to to publish such a stable build automatically to omar.
This would also solve the backup problem: currently by calling ./sync.sh, any previous version if over-written and can only be restored from backup.
Comment 1 Philipp Hahn univentionstaff 2014-11-25 08:59:02 CET
We also need to cleanup webroot/ again:
Initially it was a template directory containing common files like CSS files, the shared feedback icon, background-images, etc.

With r50271 (Bug #33809) all *generated* PDF and HTML files were added as well to put them under version control. This resulted in out-of-space errors in Jenkins as every documentation build process now needs to checkout a huge directory, which technically not needed.

We should undo that and separate the resources stuff needed for building from the generated stuff scheduled for release.

Optional: add support for cross manual linking
Currently we only like to the top of any manual and add some descriptive text to look in a certain chapter. DocBooks supports direct linking to specific chapters and sections as well, but this requires some more work: The Makefile already contains code to build the so-called "olink" database, which links the XML-ID to the target HREF. What's missing is some "magic" to rebuild all depending documents again if a link changes. This is not trivial, as documents might contain cyclic references.
Comment 2 Philipp Hahn univentionstaff 2015-04-02 08:20:52 CEST
(In reply to Philipp Hahn from comment #1)
> We also need to cleanup webroot/ again:
> Initially it was a template directory containing common files like CSS
> files, the shared feedback icon, background-images, etc.
> 
> With r50271 (Bug #33809) all *generated* PDF and HTML files were added as
> well to put them under version control. This resulted in out-of-space errors
> in Jenkins as every documentation build process now needs to checkout a huge
> directory, which technically not needed.
> 
> We should undo that and separate the resources stuff needed for building
> from the generated stuff scheduled for release.

This was done as part of Bug #36987.
The merged webroot is now tracked in <svn+ssh://billy.knut.univention.de/var/svn/dev/trunk/docs.univention.de>

(In reply to Philipp Hahn from comment #0)
> 1. Don't install to webroot by default, but rename the current "export" to
> "install" (for consistency with Makefile standard naming scheme). This
> should not be called by default (all), but only after the QA phase. The
> destination directory should be changeable to allow local test installations
> (by default) , but also final installations after QA.

The target is already named "install".
Installation to local and staging is already possible specifying DESTDIR=... This is described in <https://hutten.knut.univention.de/mediawiki/index.php/Hinweise_zur_UCS-Dokumentation#Installation_der_Dokumentation>

> 2. Jenkins currently already builds all documentations, which guarantees a
> consistent build tool chain. Currently a single job builds all
> documentations. Which could be split into different jobs; one for each
> document.

This is already done: We have one Jenkins job per document (actually extended-doc/ contains multiple documents).

> Builds can be tagged as stable, which are then stored forever. A second jobs
> can be triggered manually to to publish such a stable build automatically to
> omar.

This is missing.

> This would also solve the backup problem: currently by calling ./sync.sh,
> any previous version if over-written and can only be restored from backup.

This is already solved by using <svn+ssh://billy.knut.univention.de/var/svn/dev/trunk/docs.univention.de>


(In reply to Philipp Hahn from comment #1)
> Optional: add support for cross manual linking

This is still to do.