Thanks Lorina for all your work. +1 Your proposal makes sense to me.
Le mer. 6 oct. 2021 à 00:34, Lorina Poland <lor...@datastax.com> a écrit : > 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 >
