Versions for each feature

[OmarBazaraa]

ClickHouse gets new features constantly and continuously, and the new features, settings, configurations, ..etc. get documented regularly on https://clickhouse.com/docs. It will be so nice and useful if the docs mention when a new feature was introduced or changed.

For example, for lightweight deletes, it will be nice if the docs mentions when the feature:

1. Was first introduced as an experimental feature
2. Became production ready and available by default in the server

Another example would be for settings and configurations. If the default value of a server setting changed from x to y on version v, then it will be useful to mention in the docs that:

1. The default value is x.
2. And starting from version v, the default value became y.

Basically mentioning the history of features and default values.

And thanks so much for the great product, ClickHouse!

[tbragin]

cc @melvynator FYI

[johnnymatthews]

I've given this the X-Large size flag since it'll be a huge amount of work to go through all the existing docs/settings/functions/features and add this added in version XYZ status. I'm not saying we shouldn't do this -- having this status would be super valuable. I'm just setting expectations that this isn't an easy nor quick fix.

This would be a project all on it's own, similar to the functions-project the docs team is currently dealing with.

[OmarBazaraa]

Yeah I understand it'd be a huge effort. Starting with the new features/changes would still be beneficial tho.
And thanks a lot!

[Andersson007]

Opened an issue with an alternative solution #2492

[gingerwizard]

@Andersson007 comment

Hello,

The community is developing an Ansible collection for ClickHouse and often struggles with the docs having no versions.

There was a similar issue reported in #2125 but i would suggest not mentioning the version (it'd also work and better than nothing) but creating version-specific docs, in other words, be able to choose a version of ClickHouse similar like in PostgreSQL

It could be based on building docs from corresponding branches matching clickhouse versions.

Would make user life way easier.

[gingerwizard]

Two high level approaches proposed:

1. Version specific documentation like Postgres
2. Tag each feature with a:

• Experimental version
• Beta version
• GA version
• Default values for specific versions

This requires the same core task - go through every feature, function, type etc and identify when it was released and hoiw its changed over time.

With this information we can decide if we go for (1) or (2). Imo (1) is cleaner and more maintainable if done right. It will be harder if we backport changes in behavior but i dont think this would be considerable.

For scalability (mainly build performance) we'd need a solution which uses hard linking ideally - i.e. the same page is used for all versions until a change occurs.

The easiest thing to possibly do is only do versionning moving forward. This doesnt solve the issue immediately but after two LTS versions i think we'd be k as the user base reduced.