René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Recommended command line best practice to expose version","articleBody":"We should recommend best practice for version information (and check what already exist for that), given a command line tool.\r\n\r\n_TODO: Find/link to tool author guides_\r\n\r\nFor instance:\r\n\r\n## Level 0\r\n\r\n* MUST have a programmatic way to get version info \r\n* Parameter SHOULD be `--version` but MAY be arbitrarily named\r\n\r\n```shell\r\n$ tool -custom-version-parameter`\r\n\u003e 1.2.3\r\n```\r\n\r\n## Level 1\r\n\r\n* MUST respond to parameter `--version`\r\n* MUST include tool name\r\n* MUST include version number\r\n* Version number SHOULD be [semantic version](https://semver.org/spec/v2.0.0.html) (_TODO: How can you tell?_)\r\n\r\n\r\n```shell\r\n$ python --version\r\nPython 3.7.1\r\n```\r\n\r\n## Level 2\r\n\r\n* MUST support/include detailed version info\r\n* SHOULD support `--version --verbose`\r\n* SHOULD list important dependencies and their versions\r\n* MAY recursively ask dependencies for detailed version info (_TODO: How to show nesting?_)\r\n\r\n```shell\r\n$ python --version -V\r\nPython 3.7.1 (default, Dec 14 2018, 19:28:38) \r\n[GCC 7.3.0]\r\n```\r\n\r\n```shell\r\n$ latex --version --verbose\r\npdfTeX 3.14159265-2.6-1.40.18 (TeX Live 2017/Debian)\r\nkpathsea version 6.2.3\r\nCopyright 2017 Han The Thanh (pdfTeX) et al.\r\nThere is NO warranty.  Redistribution of this software is\r\ncovered by the terms of both the pdfTeX copyright and\r\nthe Lesser GNU General Public License.\r\nFor more information about these matters, see the file\r\nnamed COPYING and the pdfTeX source.\r\nPrimary author of pdfTeX: Han The Thanh (pdfTeX) et al.\r\nCompiled with libpng 1.6.34; using libpng 1.6.34\r\nCompiled with zlib 1.2.11; using zlib 1.2.11\r\nCompiled with poppler version 0.62.0\r\n\r\n```\r\n\r\n## Level 3\r\n\r\n* MUST support structured version info\r\n* MUST support `--version=cff`\r\n* MUST return *only* valid [CITATION.cff](https://citation-file-format.github.io/) YAML/JSON content on stdout\r\n* SHOULD include a CFF `references` section\r\n* Dependencies SHOULD be listed as  `software` under `references`\r\n* MAY recurse call `--version=cff`on tools and embed result in their `references` item\r\n\r\n_TODO: Check if anything already supports something like this_\r\n\r\n```shell\r\n$ tool --version=cff\r\ncff-version: 1.0.3\r\nmessage: If you use this software, please cite it as below.\r\nauthors:\r\n  - family-names: Druskat\r\n    given-names: Stephan\r\n    orcid: https://orcid.org/0000-0003-4925-7248\r\ntitle: My Research Tool\r\nversion: 1.0.4\r\ndoi: 10.5281/zenodo.1234\r\ndate-released: 2017-12-18\r\n```","author":{"url":"https://github.com/stain","@type":"Person","name":"stain"},"datePublished":"2019-07-27T09:33:43.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/6/software-usage-reporting/issues/6"}