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
