I am starting to slowly but surely share same opinion. Maybe we should just stop advancing this discussion altogether and we should rather focus on a way how to implement alternative output to nodetool etc. We probably need to do this command by command.
________________________________________ From: Eric Evans <eev...@wikimedia.org> Sent: Thursday, July 13, 2023 17:09 To: dev@cassandra.apache.org Subject: Re: Changing the output of tooling between majors You don't often get email from eev...@wikimedia.org. Learn why this is important<https://aka.ms/LearnAboutSenderIdentification> NetApp Security WARNING: This is an external email. Do not click links or open attachments unless you recognize the sender and know the content is safe. On Thu, Jul 13, 2023 at 9:44 AM Miklosovic, Stefan <stefan.mikloso...@netapp.com<mailto:stefan.mikloso...@netapp.com>> wrote: For example Dinesh said this: "Until nodetool can support JSON as output format for all interaction and there is a significant adoption in the user community, I would strongly advise against making breaking changes to the CLI output." That is where I get the need to have a JSON output in order to fix a typo from. That is if we look at fixing a typo as a breaking change. Which I would say it is as if somebody is "greping" it and it is not there, it will break. Do you understand that the same way or am I interpreting that wrong? I interpreted this to mean: If we want to get to a place where we can freely edit human-readable output formats, we should provide stable alternatives. ________________________________________ From: C. Scott Andreas <sc...@paradoxica.net<mailto:sc...@paradoxica.net>> Sent: Thursday, July 13, 2023 16:35 To: dev@cassandra.apache.org<mailto:dev@cassandra.apache.org> Cc: dev Subject: Re: Changing the output of tooling between majors NetApp Security WARNING: This is an external email. Do not click links or open attachments unless you recognize the sender and know the content is safe. > "From what I see you guys want to condition any change by offering json/yaml > as well." I don't think I've seen a proposal to block changes to nodetool output on machine-parseable formats in this thread. Additions of new delimited fields to nodetool output are mostly straightforward. Changes to fields that exist today are likely to cause problems - as Josh mentions. These seem best to take on a case-by-case basis rather than trying to hammer out an abstract policy. What changes would you like to make? I do think we will have difficulty evolving output formats of text-based Cassandra tooling until we offer machine-parseable output formats. – Scott On Jul 13, 2023, at 6:39 AM, Josh McKenzie <jmcken...@apache.org<mailto:jmcken...@apache.org>> wrote: I just find it ridiculous we can not change "someProperty: 10" to "Some Property: 10" and there is so much red tape about that. Well, we're talking about programmatic parsing here. This feels like complaining about a compiler that won't let you build if you're missing a ; We can change it, but that doesn't mean the aggregate cost/benefit across our entire ecosystem is worth it. The value of correcting a typo is pretty small, and the cost for everyone downstream is not. This is why we should spellcheck things in API's before we release them. :) On Wed, Jul 12, 2023, at 2:45 PM, Miklosovic, Stefan wrote: Eric, I appreciate your feedback on this, especially more background about where you are comming from in the second paragraph. I think we are on the same page afterall. I definitely understand that people are depending on this output and we need to be careful. That is why I propose to change it only each major. What I feel is that everybody's usage / expectations is little bit different and outputs of the commands are very diverse and it is hard to balance this so everybody is happy. I am trying to come up with a solution which would not change the most important commands unnecessarily while also having some free room to tweak the existing commands where we see it appropriate. I just find it ridiculous we can not change "someProperty: 10" to "Some Property: 10" and there is so much red tape about that. If I had to summarize this whole discussion, the best conclustion I can think of is to not change what is used the most (this would probably need to be defined more explicitly) and if we have to change something else we better document that extensively and provide json/yaml for people to be able to divorce from the parsing of human-readable format (which probably all agree should not happen in the first place). What I am afraid of is that in order to satisfy these conditions, if, for example, we just want to fix a typo or the format of a key of some value, the we would need to deliver JSON/YAML format as well if there is not any yet and that would mean that the change of such triviality would require way more work in terms of the implementation of JSON/YAML format output. Some commands are quite sophisticated and I do not want to be blocked to change a field in human-readable out because providing corresponding JSON/YAML format would be gigantic portion of the work itself. From what I see you guys want to condition any change by offering json/yaml as well and I dont know if that is just not too much. ________________________________________ From: Eric Evans <eev...@wikimedia.org<mailto:eev...@wikimedia.org><mailto:eev...@wikimedia.org<mailto:eev...@wikimedia.org>>> Sent: Wednesday, July 12, 2023 19:48 To: dev@cassandra.apache.org<mailto:dev@cassandra.apache.org><mailto:dev@cassandra.apache.org<mailto:dev@cassandra.apache.org>> Subject: Re: Changing the output of tooling between majors You don't often get email from eev...@wikimedia.org<mailto:eev...@wikimedia.org><mailto:eev...@wikimedia.org<mailto:eev...@wikimedia.org>>. Learn why this is important<https://aka.ms/LearnAboutSenderIdentification> NetApp Security WARNING: This is an external email. Do not click links or open attachments unless you recognize the sender and know the content is safe. On Wed, Jul 12, 2023 at 1:54 AM Miklosovic, Stefan <stefan.mikloso...@netapp.com<mailto:stefan.mikloso...@netapp.com><mailto:stefan.mikloso...@netapp.com<mailto:stefan.mikloso...@netapp.com>><mailto:stefan.mikloso...@netapp.com<mailto:stefan.mikloso...@netapp.com><mailto:stefan.mikloso...@netapp.com<mailto:stefan.mikloso...@netapp.com>>>> wrote: I agree with Jackson that having a different output format (JSON/YAML) in order to be able to change the default output resolves nothing in practice. As Jackson said, "operators who maintain these scripts aren’t going to re-write them just because a better way of doing them is newly available, usually they’re too busy with other work and will keep using those old scripts until they stop working". This is true. If this approach is adopted, what will happen in practice is that we change the output and we provide a different format and then a user detects this change because his scripts changed. As he has existing solution in place which parses the text from human-readable output, he will try to fix that, he will not suddenly convert all scripting he has to parsing JSON just because we added it. Starting with JSON parsing might be done if he has no scripting in place yet but then we would not cover already existing deployments. I think this is quite an extreme conclusion to draw. If tooling had stable, structured output formats, and if we documented an expectation that human-readable console output was unstable, then presumably it would be safe to assume that any new scripters would avail themselves of the stable formats, or expect breakage later. I think it's also fair to assume that at least some people would spend the time to convert their scripts, particularly if forced to revisit them (for example, after a breaking change to console output). As someone who manages several large-scale mission-critical Cassandra clusters under constrained resources, this is how I would approach it. TL;DR Don't let perfect by the enemy of good<https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FPerfect_is_the_enemy_of_good&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C0fd0cb90db3a4900fc4408db83b32f0e%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638248577861891902%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C&sdata=Rxsf2zfDvTTZa7kn40haKF9rk4jy4W3uwCWR33SY3bA%3D&reserved=0><https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FPerfect_is_the_enemy_of_good&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7Ca05ce5e1602946efc1fb08db83ae73bc%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638248557516576810%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=8j5RTNRt0scXO7Fgi0C5rgzKT16cqNqLIfwU96qlfso%3D&reserved=0<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FPerfect_is_the_enemy_of_good&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C0fd0cb90db3a4900fc4408db83b32f0e%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638248577861891902%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C2000%7C%7C%7C&sdata=Rxsf2zfDvTTZa7kn40haKF9rk4jy4W3uwCWR33SY3bA%3D&reserved=0>>> [ ... ] For that reason, what we could agree on is that we would never change the output for "tier 1" commands and if we ever changed something, it would be STRICT ADDITIONS only. In other words, everything it printed, it would continue to print that for ever. Only new lines could be introduced. We need to do this because Cassandra is evolving over time and we need to keep the output aligned as new functionality appears. But the output would be backward compatible. Plus, we are talking about majors only. The only reason we would ever changed the output on "tier 1" commands, if is not an addition, is the fix of the typo in the existing output. This would again happened only in majors. All other output for all other commands might be changed but their output will not need to be strictly additive. This would again happen only between majors. What is you opinion about this? To be clear about where I'm coming from: I'm not arguing against you or anyone else making changes like these (in major versions, or otherwise). If —for example— we had console output that was incorrect, incomplete, or obviously misleading, I'd absolutely want to see that fixed, script breakage be damned. All I want is for folks to recognize the problems this sort of thing can create, and show a bit of empathy before submitting a change. For operators on the receiving end, it can be really frustrating, especially when there is no normative change (i.e. it's in service of aesthetics). -- Eric Evans<mailto:eev...@wikimedia.org<mailto:eev...@wikimedia.org><mailto:eev...@wikimedia.org<mailto:eev...@wikimedia.org>>> Staff SRE, Data Persistence Wikimedia Foundation -- Eric Evans<mailto:eev...@wikimedia.org> Staff SRE, Data Persistence Wikimedia Foundation
