3

In the context of a Java/Maven/Markdown/Git project - what's the most elegant way to break the build if command lines featured in the project readme file stopped working after the code change.

The one I can think of is have an ant task that would grep the README.md for specific markers, extract the code, and execute it. Wondering if someone has solved the subject problem in a more elegant way.

The reason is to prevent the examples in the documentation from going stale.

bobah
  • 18,364
  • 2
  • 37
  • 70
  • How about making the commands used in the documentation part of the normal test-cases? If the documentation is updated with new or changed commands and options, those must then be part of the normal testing procedures (as well as come from proper requirements, analysis and design of course). – Some programmer dude Aug 21 '18 at 08:49
  • @Someprogrammerdude - then the tests and the doc will have to have the same "master source" of the command lines, to prevent them from going out of sync, so the problem remains (slightly changed in formulation) – bobah Aug 21 '18 at 08:54
  • 2
    Why not going other way around and running tests for your code examples and a final step extracting the code and put them into the docs ? – khmarbaise Aug 21 '18 at 09:01
  • @khmarbaise - in this case the question becomes "inject markdown README with command lines used in tests and "committing the generated readme when a material change is detected". The "material change" is another bit that may complicate it - you don't want to create code commits when timestamps of the logs of the sample commands have changed, for instance. Lots of small annoying details which need ironing out. – bobah Aug 21 '18 at 09:43

0 Answers0