Recommended command line best practice to expose version

[stain]

We should recommend best practice for version information (and check what already exist for that), given a command line tool.

TODO: Find/link to tool author guides

For instance:

Level 0

• MUST have a programmatic way to get version info
• Parameter SHOULD be --version but MAY be arbitrarily named

$ tool -custom-version-parameter`
> 1.2.3

Level 1

• MUST respond to parameter --version
• MUST include tool name
• MUST include version number
• Version number SHOULD be semantic version (TODO: How can you tell?)

$ python --version
Python 3.7.1

Level 2

• MUST support/include detailed version info
• SHOULD support --version --verbose
• SHOULD list important dependencies and their versions
• MAY recursively ask dependencies for detailed version info (TODO: How to show nesting?)

$ python --version -V
Python 3.7.1 (default, Dec 14 2018, 19:28:38) 
[GCC 7.3.0]

$ latex --version --verbose
pdfTeX 3.14159265-2.6-1.40.18 (TeX Live 2017/Debian)
kpathsea version 6.2.3
Copyright 2017 Han The Thanh (pdfTeX) et al.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Han The Thanh (pdfTeX) et al.
Compiled with libpng 1.6.34; using libpng 1.6.34
Compiled with zlib 1.2.11; using zlib 1.2.11
Compiled with poppler version 0.62.0

Level 3

• MUST support structured version info
• MUST support --version=cff
• MUST return only valid CITATION.cff YAML/JSON content on stdout
• SHOULD include a CFF references section
• Dependencies SHOULD be listed as software under references
• MAY recurse call --version=cffon tools and embed result in their references item

TODO: Check if anything already supports something like this

$ tool --version=cff
cff-version: 1.0.3
message: If you use this software, please cite it as below.
authors:
  - family-names: Druskat
    given-names: Stephan
    orcid: https://orcid.org/0000-0003-4925-7248
title: My Research Tool
version: 1.0.4
doi: 10.5281/zenodo.1234
date-released: 2017-12-18

[yochannah]

This is a great start - adding in some related reading / possible cite: https://gigascience.biomedcentral.com/articles/10.1186/2047-217X-2-15