[ 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: commits-unsubscr...@cassandra.apache.org For additional commands, e-mail: commits-h...@cassandra.apache.org