Univention Bugzilla – Bug 30532
Rework release process for documentation
Last modified: 2024-04-17 13:16:46 CEST
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.
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.
(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.
This bug hasn't seen any update for several years. I close it. If you still see a need for it, you can reopen the bug. Please add an argumentation about why it's important to take care of it.