Hey Stefan, Thank you for your support and spending the time to think about this.
If I understand you correctly, you suggest reopening the old tickets to finish the docs, I have two concerns: - we might work a few times on one and the same doc until we bring it to the latest state instead of getting a doc to latest state at once. I think that’s what Anthony was trying to take care of in his approach, to save some time? No? - Reopening old tickets which primary goal is not the docs brings more confusion, in my opinion. Otherwise, I think we have a required field for Testing and docs but splitting those in two and being more diligent around that might be a good idea? Thanks again, Ekaterina On Wed, 13 Oct 2021 at 3:27, Stefan Miklosovic < stefan.mikloso...@instaclustr.com> wrote: > Hey, > > I got an idea how this might be simplified. > > Every commit in Cassandra repository belongs to a ticket (except > ninjas but they are irrelevant here). > > So if you look over the commits, what about looking at what Jira > ticket they belong to (this information is in each commit message) and > then go to that Jira and label that with "need-docs-backported" or > something like that? > > The idea here is that we can filter tickets like these and if we fix > it / backport it (under the same Jira ticket number), we will just > remove that label and the work is done if there are no tickets with > such label anymore. > > Hence we do not create any additional ticket at all, we may even > reopen tickets which are resolved now. > > Regards > > On Mon, 11 Oct 2021 at 01:06, Anthony Grasso <anthony.gra...@gmail.com> > wrote: > > > > Hi Stefan, > > > > I agree with your thoughts around grouping together changes touching a > > subsystem. This is exactly how I started doing the backporting work a few > > weeks ago. For example I started by looking at all the changes in the > > 'doc/source/architecture' folder of the rST docs, and back ported only > > those. > > > > I propose every subsection (child folder in doc/source/; e.g. > > 'architecture', 'configuration', 'cql') that has rST doc changes dating > > back to June 2020 has a ticket. Each ticket would list the commit hashes > > that need to be backported. For commit hashes that span multiple > > subsections we pick a single ticket for that hash to be done under. This > > will allow us to divide up the work fairly easily with minimal conflicts > > when merging. > > > > This process would need to be done for both Cassandra 3.11 and 4.0/trunk. > > > > We can use CASSANDRA-16761 > > <https://issues.apache.org/jira/browse/CASSANDRA-16761> as the umbrella > > ticket for these changes. This epic was opened to capture all the work > > related to migrating from the old website and rTS docs to the new website > > and AsciiDoc. It is the ideal location for the tickets which will capture > > the backporting work. > > > > Kind regards, > > Anthony > > > > > > > > On Sat, 9 Oct 2021 at 04:02, Ekaterina Dimitrova <e.dimitr...@gmail.com> > > wrote: > > > > > Hey Stefan, > > > > > > Thank you for your response. > > > > > > “If it was feasible to gather all related changes touching a subsystem > > > under one umbrella ticket, that would be very nice but I do not know > > > if that makes sense from your point of view (what workflow you have).” > > > > > > It is up to us to decide what would be the most efficient way how to > move > > > forward as a community so any ideas are appreciated. I think Anthony > had > > > similar idea to what you said. Probably he can share more details. > > > > > > Best regards, > > > Ekaterina > > > > > > On Thu, 7 Oct 2021 at 3:32, Stefan Miklosovic < > > > stefan.mikloso...@instaclustr.com> wrote: > > > > > > > Hi Lorina, Ekaterina, > > > > > > > > In general your approach sounds good to me. I am also +1 on not > > > > creating too many tickets as I can see it will be easy to get lost > in. > > > > > > > > If it was feasible to gather all related changes touching a subsystem > > > > under one umbrella ticket, that would be very nice but I do not know > > > > if that makes sense from your point of view (what workflow you have). > > > > > > > > Regards > > > > > > > > On Wed, 6 Oct 2021 at 23:56, Ekaterina Dimitrova < > e.dimitr...@gmail.com> > > > > wrote: > > > > > > > > > > Hey Lorina, > > > > > > > > > > First of all - thank you so much for all the work done by you and > the > > > > rest > > > > > of the people! The website and the docs are our front door as a > > > project! > > > > > > > > > > +1 on your proposal. My understanding is we need 1)+5) and then > > > > everything > > > > > else will be able to roll out and more people will be able to join > the > > > > > efforts so we can knock out 2) which seems the biggest work here, > did I > > > > get > > > > > it correct? > > > > > > > > > > My only comment is about the tickets we will have to open. I can > > > suggest > > > > we > > > > > don’t do 1:1 ticket for every small backport ticket/change but 1:1 > for > > > > > bigger bodies of work and 1:many where we see we can combine a few > > > > smaller > > > > > changes so we don’t deal with too many tickets. Does this sound > > > > reasonable? > > > > > Is there a different suggestion or plan? > > > > > > > > > > Thank you one more time. I will be happy to help with what I can > do in > > > > > order to bring this to the finish line. I am sure others will do > too > > > even > > > > > with a ticket or two :-) In OSS every single contribution matter, > > > right? > > > > > > > > > > Best regards, > > > > > Ekaterina > > > > > > > > > > On Wed, 6 Oct 2021 at 8:22, Benjamin Lerer <ble...@apache.org> > wrote: > > > > > > > > > > > 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 > > > > > > > > > > > > > > > > > > > > > --------------------------------------------------------------------- > > > > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > > > > For additional commands, e-mail: dev-h...@cassandra.apache.org > > > > > > > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > For additional commands, e-mail: dev-h...@cassandra.apache.org > >
