Project

General

Profile

Feature #4044

regenerate vty reference during release process

Added by laforge 21 days ago. Updated 20 days ago.

Status:
New
Priority:
Normal
Assignee:
Target version:
-
Start date:
06/04/2019
Due date:
% Done:

0%

Spec Reference:

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

Related to Cellular Network Infrastructure - Feature #3695: generate VTY reference manuals from 'make' directlyNew

Related to libosmocore - Feature #4053: CTRL: Add CTRL cmd introspection to print documentationNew06/10/2019

History

#1 Updated by osmith 20 days ago

  • Related to Feature #3695: generate VTY reference manuals from 'make' directly added

#2 Updated by pespin 20 days 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.

#3 Updated by osmith 20 days ago

What is the advantage of that compared to always generating the vty reference when building the pdfs? If we did the latter, then we don't need to have the reference.xml changed in the patches, and we don't need to remember to update the file.

#4 Updated by laforge 20 days 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 20 days 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 20 days 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 15 days ago

  • Related to Feature #4053: CTRL: Add CTRL cmd introspection to print documentation added

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)