[
https://issues.apache.org/jira/browse/CASSANDRA-19767?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17866029#comment-17866029
]
Stefan Miklosovic commented on CASSANDRA-19767:
-----------------------------------------------
Unfortunately, I am not sure this is what we want. The logic behind writing
that documentation is that a respective user can just un-comment the whole
block of the docs, tweak the values and it would just work. The way how
startup_checks were treated here indeed fixes the rendering issue, but it
becomes quite counter-intuitive for anybody who is modifying that file by hand
as they would need to copy over whole configuration sections for respective
configuration property.
I do not know what is the best to do there. I tried to play with the rendering
but it does not do what I want.
One solution would be to move startup_checks to the very bottom of
cassandra.yaml so it will not be merged together with
storage_compatibility_mode.
> Fix storage_compatibility_mode and startup_checks documentation
> ---------------------------------------------------------------
>
> Key: CASSANDRA-19767
> URL: https://issues.apache.org/jira/browse/CASSANDRA-19767
> Project: Cassandra
> Issue Type: Task
> Components: Documentation
> Reporter: Jackson Fleming
> Assignee: Jackson Fleming
> Priority: Normal
> Labels: Documentation
> Fix For: 4.1.x, 5.0.x, 5.x
>
> Attachments: image-2024-07-12-09-38-16-284.png
>
> Time Spent: 50m
> Remaining Estimate: 0h
>
> The documentation for storage_compatibility_mode
> ([https://cassandra.apache.org/doc/latest/cassandra/managing/configuration/cass_yaml_file.html#storage_compatibility_mode])
> is very difficult to read. The below highlighted text seems incorrect.
> !image-2024-07-12-09-38-16-284.png|width=505,height=487!
>
> It appears that the entry for the YAML option above it is causing entries to
> get clobbered together (startup_checks)
>
> This is actually a very useful and important feature for people upgrading to
> Cassandra 5 to understand how to use properly - It would be good for it to be
> easier to read, we should be encouraging use of the safest possible upgrade
> path, which from my understanding would be:
> {{CASSANDRA_4 -> UPGRADING -> NONE}}
>
>
> Update - seems like the startup_checks docs is also missing in the 4.1 pages,
> I'll fix that as well.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
