docs: need new release note category for operational changes

[knz]

We have a bunch of changes that affect the life of system operators, or DBAs responsible for orchestration etc.

Today the release note categories do not offer a way to target that audience specifically. We only have:

- "api change" for the HTTP APIs
- "cli change" for the command line interfaces
- "security update" for changes that interest the security auditors

None of these are particularly suitable for changes like:

• new behavior of network listeners
• new ways that data gets logged (e.g network logging)
• new contents for logged messages
• new constraints on how servers accept to connect to each other

What would be a way forward? I would be tempted to introduce a new category "server change" for this purpose.

cc @jseldess @taroface for triage

[taroface]

@knz "server change" (or "network change") makes sense to me for the first and last, but I wonder if the middle two would also call for a "log change"? Or would DB operators expect to find all four updates in the same place?

[knz]

I think server/network/log all under fall a common group, which is "things that operators (the folk who set up orchestration, operational integrations, monitoring etc) have to care about".

Maybe the shorthand "server" is not right, and we'd like "operator changes" instead? I'm fine with that. I don't think we need a more fine grained distinction however.

What do you think?

(This need came up again in last week PRs)

[taroface]

I think "operator" is used in enough other contexts (SQL operator, K8s Operator) that it would be potentially confusing here.

What about "system change"? This is also very broad, but maybe covers the bases while conveying something distinct from cli/api/security?

[jseldess]

To avoid the potentially overloaded operator term, what about Operational changes? But this opens up the question: Wouldn't a lot of cli and security changes fit under that category?

[knz]

I agree many but not all cli changes would fall under that new umbrella. Sec changes, not so much.

I am looking at this from the perspective of the audience.

Sec changes typically get reviewed by security architects or auditors, that's a different crowd from the operators or SREs.

The CLI in contrast has 3 audiences really. Operators, app developers and crdb team members.

We can refine the scope boundaries for "cli changes" to the ussr-facing changes that affect app developers. This includes demo, sql, userfile etc

But these features (demo, sql, userfile etc) definitely do not have the operator as main audience.

Hence in my view there is value in retaining "cli changes" side by side with the new category.

[jseldess]

Yeah, we might want to take another shot at reviewing these categories more holistically. But ahead of that, I'm ok with adding this.

[knz]

proposal: #59051
I also modified the wiki page with this proposal

[jseldess]

Thanks, @knz. I'm ok with this, but I feel like the logic of our categorizations is getting (probably has been) inconsistent and confusing. For example, some categories focus on interface (cli change), others focus on audience role (operational change, security change). Yet others go across everything (bug fixes, performance changes). And now even one of the interface categories (cli change) only captures the parts of the interface that impact a single audience (app devs). Feels strange to me.

Another approach would be to organize release notes more by product area, like we do in our GA release notes: https://www.cockroachlabs.com/docs/releases/v20.2.0#feature-summary. That would mean putting all kinds of changes under each, from new features to changes to fixes, etc. Not at all sure about this, but perhaps we take an existing release notes document and try a few variations as an experiment?

[knz]

Do you remember this open PR from 2018? #29810

The idea was to separate product area from impact and present them both side-by-side.

And yes we can take one of the existing release note documents. If you recall, when 20.1.0 was released I believe I helped you with that and we ended up with categories and sub-categories becuase the bullet list was too long otherwise.