On Fri, Jul 7, 2023 at 10:20 AM Miklosovic, Stefan < stefan.mikloso...@netapp.com> wrote:
> Hi list, > > I want to clarify the policy we have when we want to / going to change the > output of the tooling (nodetool or tools/bin etc.). > > I am not sure it is written somewhere explicitly, but how I get it from > the gossip over years is that we should not change the output (e.g. > changing the name of fields etc) in minors, but for majors (4.0 -> 5.0), > this is OK, correct? > > For example, when some tool prints this: > > thisIsAStatistic: 10 > > and we see that all other lines in that output print it like this: > > This Is Another Statistic: abc > > scratching the itch is almost irresistible so we want to change the output > to: > > This Is a Statistic: 10 > > This is the natural way how fixes are done. We are improving the output, > making it consistent etc. > > Someone may argue that we are changing "public api" and people are > actually parsing the output like this and we better not to change it > because we might break "the scripts" for somebody. > If that output is (or at some earlier point, was) the most obvious way to obtain something, then for all intents and purposes it is a public api. When it's changed, you should assume it *will* break scripts. > While I get this for minors and it is understandable that minors should be > same, is this relevant for majors? Because if we care about majors too in > this situation, how are we supposed to evolve the output over time? Is it > supposed to be just frozen for ever? I do not buy this argument. For > minors, fine. But for majors, I do not think so. > Majors are expected to be more disruptive, but I don't personally interpret that as a license to be disruptive. The pain this creates isn't any less because it is a major. > > I feel like "not break the output because API" is more or less an urban > legend we keep repeating ourselves. I yet need to meet somebody who is > stressing over the fact that her output changed *between majors*. > Hi Stefan, I'm Eric, nice to meet you; I stress a great deal at all of the changes —large and small— that occur between major versions. :) They create additional work, introduce risk, and often end up delaying (by months and years even) a major upgrade. You might be surprised by the kind of breakage (often subtle) that even the smallest changes can create, or how frustrating it can be when it was only done to satisfy a sense of aesthetics. > If that is the case, we should start to treat this problem completely > differently and we should not rely on the output of tooling at all and we > should either provide corresponding JMX method to retrieve it or we should > offer other formats tooling prints, like JSON or YAML. Absolutely. But I think the right thing in this situation is to acknowledge that the console output is a contract, and act accordingly. In this case: offer (and promote) those structured replacements (JSON, YAML), document the intended instability, and follow through after a sufficient window. -- Eric Evans john.eric.ev...@gmail.com
