Discussing compatibility with some team members, we realised that we don't have anything written down about compatibility guarantees in general. There are many areas in compatibility, but for this discussion, I would like to focus on CLI command output.
Ozone is still relatively immature, and as such we often find a need to add to or modify the CLI command output to provide more information to help users of the system, or as features are added and enhanced. There are two ways the CLI commands can produce output: 1. Human readable format. 2. JSON format. The default output is "Human Readable", with JSON enabled via the "--json" flag. Not all commands support JSON at the moment, but most do, and we should endeavour to ensure they all do, and fill the gaps ASAP. I am also mainly focused on admin type commands (eg ozone admin container info etc) rather than "key listing" commands, similar to the "ls" output we know from filesystems and hadoop. However I believe "ozone sh key list" etc already provide their output in JSON format by default. I would like the community to agree on a set of compatibility principals for CLI command output, and as a starting point for discussion, I would like to propose the following: 1. We should ensure that information is never removed from command output, unless it is deprecated and removed gracefully after some number of releases. For JSON the existing field names and location in the JSON structure should remain the same. 2. Information can be added to command output, and the output is still considered compatible as all existing information is still present. 3. Following from (2), this means the format of the "Human Readable" output may change if, for example, some new field or information is added on an existing line, or new lines of output are added. 4. Due to (3), the "Human Readable" output is not intended to be consumed programmatically. We recommend only JSON be consumed programmatically, as existing structures will remain even if new information is added. Please let me know your thoughts on the above proposals, or any other suggestions in the scope of "CLI Output Compatibility" and I will bring the suggestions together into something we can publish in the docs when we reach agreement. Thanks, Stephen.
