https://osmocom.org/https://osmocom.org/favicon.ico?16647414092019-06-05T07:36:54ZOpen Source Mobile CommunicationsCellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147182019-06-05T07:36:54Zosmith
<ul><li><strong>Related to</strong> <i><a class="issue tracker-2 status-6 priority-2 priority-default closed" href="/issues/3695">Feature #3695</a>: generate VTY reference manuals from 'make' directly</i> added</li></ul> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147192019-06-05T09:08:41Zpespin
<ul></ul><p>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).</p>
<p>This way we always make sure during gerrit time that xml file is updated accordingly.</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147202019-06-05T09:20:55Zosmith
<ul></ul><p>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.</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147212019-06-05T09:39:08Zlaforge
<ul></ul><blockquote>
<p>What is the advantage of that compared to always generating the vty<br />reference when building the pdfs?</p>
</blockquote>
<p>I think it's really bad practise to require the execution of the program at<br />build time. Think of cross-compilation situations, where certainly you<br />do want to generate manuals, but you cannot [realistically, generically]<br />execute the just-built program at build time as it's for the target<br />architecture, not the architecture of your host.</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147222019-06-05T09:41:16Zpespin
<ul></ul><p>Hi <a class="user active" href="https://osmocom.org/users/301771">osmith</a> , I think I don't understand your comment. Can you extend your idea?</p>
I see several advantatges about checking during gerrit verification (for programs that support vty_tests):
<ul>
<li>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.</li>
<li>Having master documentation always up-to-date</li>
<li>Not having to do yet another step during release which basically is cleaning up mess from other people done previously</li>
</ul> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147232019-06-05T09:55:26Zosmith
<ul></ul><p>pespin wrote:</p>
<blockquote>
<p>Hi <a class="user active" href="https://osmocom.org/users/301771">osmith</a> , I think I don't understand your comment. Can you extend your idea?</p>
</blockquote>
<p>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 <a class="issue tracker-2 status-6 priority-2 priority-default closed" title="Feature: generate VTY reference manuals from 'make' directly (Rejected)" href="https://osmocom.org/issues/3695">#3695</a>.</p>
<blockquote>
I see several advantatges about checking during gerrit verification (for programs that support vty_tests):
<ul>
<li>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.</li>
</ul>
</blockquote>
<p>I get this point, if we did generate vty_reference.xml on demand only, nobody would look at how it changes during code review.</p>
<blockquote>
<ul>
<li>Having master documentation always up-to-date</li>
</ul>
</blockquote>
<p>This would also be the case if we generate the vty_reference.xml on demand.</p>
<blockquote>
<ul>
<li>Not having to do yet another step during release which basically is cleaning up mess from other people done previously</li>
</ul>
</blockquote>
<p>There would be no need for that either.</p>
<blockquote>
<p>I think it's really bad practise to require the execution of the program at<br />build time. Think of cross-compilation situations, where certainly you<br />do want to generate manuals, but you cannot [realistically, generically]<br />execute the just-built program at build time as it's for the target<br />architecture, not the architecture of your host.</p>
</blockquote>
<p>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.</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=147742019-06-10T11:22:04Zpespin
<ul><li><strong>Related to</strong> <i><a class="issue tracker-2 status-1 priority-1 priority-lowest" href="/issues/4053">Feature #4053</a>: CTRL: Add CTRL cmd introspection to print documentation</i> added</li></ul> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=149982019-06-27T08:36:41Zosmith
<ul></ul><p>I've thought about how one would implement the check in gerrit together with the regen_doc.sh scripts that <a class="user active" href="https://osmocom.org/users/30">daniel</a> created. Here's what I came up with (not adding as checklist, because this is not assigned to me):</p>
<ul>
<li>remove git hashes from generated xml files (so they don't need to be adjusted after every unrelated patch update during review process)</li>
<li>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)</li>
<li>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)</li>
<li>osmo-*.git: ./contrib/jenkins.sh: if WITH_MANUALS=1 is set, also run VERIFY=1 regen_doc.sh</li>
</ul>
<p><a class="user active" href="https://osmocom.org/users/30187">pespin</a>: would you mind if I take this issue?</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=150032019-06-27T09:44:33Zpespin
<ul><li><strong>Assignee</strong> changed from <i>pespin</i> to <i>osmith</i></li></ul><p><a class="user active" href="https://osmocom.org/users/301771">osmith</a> all yours, hearing that makes me really happy!</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=150202019-06-28T02:17:04Zlaforge
<ul></ul><p>Hi Oliver,</p>
<p>in the last phone meeting last week we discussed that <a class="user active" href="https://osmocom.org/users/52">Hoernchen</a> will look into an<br />approach to generate the vty + counter reference at compile time using inspection of<br />the parsed C source code or intermediate representation baesd on clang. This approach<br />would work at build time, even for cross-compilation cases.</p>
<p>Please don't do anything here without coordinating with Hoernchen.</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=150252019-06-28T07:39:30Zosmith
<ul><li><strong>Related to</strong> <i><a class="issue tracker-2 status-7 priority-1 priority-lowest" href="/issues/4073">Feature #4073</a>: try to get counter and vty reference information at compile time</i> added</li></ul> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=150272019-06-28T07:40:56Zosmith
<ul></ul><p>Thanks for pointing that out, I was not part of that meeting.</p> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=151652019-07-16T13:52:34Zosmith
<ul><li><strong>Status</strong> changed from <i>New</i> to <i>Stalled</i></li></ul> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=222692021-06-15T15:58:34Zlaforge
<ul><li><strong>Related to</strong> <i><a class="issue tracker-2 status-3 priority-3 priority-high3 closed" href="/issues/1700">Feature #1700</a>: Update/add counter and/or vty documentation for osmo-* programs</i> added</li></ul> Cellular Network Infrastructure - Feature #4044: regenerate vty reference during release processhttps://osmocom.org/issues/4044?journal_id=266362023-04-03T13:37:16Zosmith
<ul><li><strong>Status</strong> changed from <i>Stalled</i> to <i>Rejected</i></li></ul><p>This is now obsolete, the VTY reference gets generated while building the manuals.</p>
See:
<ul>
<li><a class="external" href="https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/18362">https://gerrit.osmocom.org/c/osmo-gsm-manuals/+/18362</a></li>
<li><a class="external" href="https://osmocom.org/issues/5041">https://osmocom.org/issues/5041</a></li>
</ul>