Feature #4044
regenerate vty reference during release process
0%
Description
now that the manuals are part of the respective program git repositories, we should somehow make sure that every time we tag a new release, the VTY reference XML is updated, ensuring [at least] the tagged versions have corresponding vty reference documentation.
I know it may not be trivial to completely automatize it. So for now I think I would be happy of the release helper prints a reminder, possibly requiring a manual --override if the vty reference xml didn't change compared to the last release? I'm open for better ideas, but at the very least a simple reminder should be present.
Related issues
History
#1 Updated by osmith 6 months ago
- Related to Feature #3695: generate VTY reference manuals from 'make' directly added
#2 Updated by pespin 6 months ago
I think it'd be best to add extra checks during VTY unit tests (like osmo-bsc/tests/vty_test_runner.py) to print "show online-help" and match it against reference.xml (osmo-bsc/doc/manuals/vty/bsc_vty_reference.xml).
This way we always make sure during gerrit time that xml file is updated accordingly.
#4 Updated by laforge 6 months ago
What is the advantage of that compared to always generating the vty
reference when building the pdfs?
I think it's really bad practise to require the execution of the program at
build time. Think of cross-compilation situations, where certainly you
do want to generate manuals, but you cannot [realistically, generically]
execute the just-built program at build time as it's for the target
architecture, not the architecture of your host.
#5 Updated by pespin 6 months ago
Hi osmith , I think I don't understand your comment. Can you extend your idea?
I see several advantatges about checking during gerrit verification (for programs that support vty_tests):- Having documentation changes together in same commit than code change, also meaning people will take more care that VTY defined function will have all proper strings in place.
- Having master documentation always up-to-date
- Not having to do yet another step during release which basically is cleaning up mess from other people done previously
#6 Updated by osmith 6 months ago
pespin wrote:
Hi osmith , I think I don't understand your comment. Can you extend your idea?
Sure. What I meant was getting rid of the vty_reference.xml file entirely, and only generating it at build time. This is also how I understood the proposal in #3695.
I see several advantatges about checking during gerrit verification (for programs that support vty_tests):
- Having documentation changes together in same commit than code change, also meaning people will take more care that VTY defined function will have all proper strings in place.
I get this point, if we did generate vty_reference.xml on demand only, nobody would look at how it changes during code review.
- Having master documentation always up-to-date
This would also be the case if we generate the vty_reference.xml on demand.
- Not having to do yet another step during release which basically is cleaning up mess from other people done previously
There would be no need for that either.
I think it's really bad practise to require the execution of the program at
build time. Think of cross-compilation situations, where certainly you
do want to generate manuals, but you cannot [realistically, generically]
execute the just-built program at build time as it's for the target
architecture, not the architecture of your host.
True, I did not think of the cross-compilation case. With that in mind, I guess doing it like Pau suggested would be the best way, ensuring that the xml file is always up-to-date with CI.
#7 Updated by pespin 6 months ago
- Related to Feature #4053: CTRL: Add CTRL cmd introspection to print documentation added
#8 Updated by osmith 5 months ago
I've thought about how one would implement the check in gerrit together with the regen_doc.sh scripts that daniel created. Here's what I came up with (not adding as checklist, because this is not assigned to me):
- remove git hashes from generated xml files (so they don't need to be adjusted after every unrelated patch update during review process)
- docker-playground.git: do git checkout for repositories from gerrit, not from git.osmocom.org (so we will have git commits present, that are in review state and not yet in master)
- docker-playground.git: scripts/regen_doc.sh: add VERIFY environment variable, and when it is set, verify if the xml files changed after regenerating them (exit with 1 on change)
- osmo-*.git: ./contrib/jenkins.sh: if WITH_MANUALS=1 is set, also run VERIFY=1 regen_doc.sh
pespin: would you mind if I take this issue?
#10 Updated by laforge 5 months ago
Hi Oliver,
in the last phone meeting last week we discussed that @Hoernchen will look into an
approach to generate the vty + counter reference at compile time using inspection of
the parsed C source code or intermediate representation baesd on clang. This approach
would work at build time, even for cross-compilation cases.
Please don't do anything here without coordinating with Hoernchen.
#11 Updated by osmith 5 months ago
- Related to Feature #4073: try to get counter and vty reference information at compile time added