This is a discussion about how to tackle getting the docs “fixed”. As many of you know, I started months ago to convert the Apache Cassandra in-tree docs from reStructedText (rST)to AsciiDoc. [1] The conversion required both the docs source files to be converted, but also the cassandra-website source to be updated, to build the docs from AsciiDoc.[2] You all have seen the results of that conversion + the beautiful new design work accomplished. When Apache Cassandra 4.0 was ready to GA, we used my private repo (polandll/cassandra) to build the docs for publication. (The new cassandra-website procedure allows for any repo to be used to build.) Due to a series of interferences with virtually all the people on the project (myself, Anthony Grasso, Mick Semb Wever, Paul Lau) in the time leading up to the GA or right after, we have never gotten my repo work committed and merged to the official source (apache/cassandra). So, here is the proposal for a plan of action:
(1) Anthony and Lorina get the 4.0/trunk and 3.11 branches that Lorina worked on for the last 18 months ready for merge from polandll/cassandra -> apache/cassandra. (2) There are changes that were made in the last 18 months to docs (in the current rST docs) that need to be backported to the new adoc docs. We can use the commit history to hunt down those changes and make tickets for each of them. Those tickets can be listed under an umbrella ticket. (3) There are tickets that already exist that I asked people to wait on merging during the conversion. Those tickets also need to be completed. (4) There are a few tickets for PRs people submitted to my private repo (oh my!) that should be completed again in the official repo. (5) I will write a “how to contribute to docs” that gives people a rundown of how to write AsciiDoc. We would like to merge the docs in their current state, step (1), then make the backports, rather than make the backports then merge to the apache/cassandra repo. Main reason for this order is that, at least the docs and website could be built from official repos once that is done. Until the adoc conversion is merged, the docs and website can only be built from my personal repo, which is a sad situation. Lastly, just to clarify the work we want to merge. I modified the trunk for 4.0 and made all the changes required. (750+ files). Then, rather than modify the 3.11 branch, I wrote trunk to 3.11 and removed the “What’s new” folder (called /new, unimaginatively). I had planned to then go back and incorporate the "What’s new" material into the appropriate places in the 4.0 docs, because, in short order, those changes are no longer what’s new. [1] https://lists.apache.org/thread.html/r42802f86d7893c42b5091fe7f7d4b048a63cbe0fd11fadcd120596e3%40%3Cdev.cassandra.apache.org%3E [2] https://lists.apache.org/thread.html/r961c52f58a42a3b2cae7299244a525311283cd2758d0201f8b0feb83%40%3Cdev.cassandra.apache.org%3E
