Hi Anthony, Benjamin, all, I am back :)
So I closed two tiny tickets(CASSANDRA-16894 and CASSANDRA-17182) with docs and website updates last week and in my opinion things are quite straightforward if there are no additional changes to script/process planned. (Thanks Mick for confirming things for me, I might add just a small PR with a few comments to the docs/website readme but overall things are already there) Shall we continue with opening an epic and initiating a docs update campaign? Let me know how I can help. Best regards, Ekaterina On Tue, 11 Jan 2022 at 8:02, Ekaterina Dimitrova <e.dimitr...@gmail.com> wrote: > Hi Anthony, > > Great news! Thanks everyone for all the work and time invested. IMHO docs > are as important as well written code. > > “Would we reopen it to fix the problem or would we open a new ticket? Do > we have project guidelines around this? I would think in this scenario a > new ticket would be created?” > I am not sure of particular guideline written somewhere but we normally we > open a new ticket and we link it to the old one. > > About organizing the work, I think the idea of splitting by area of docs > and opening ticket per package maybe sounds reasonable. This should cover > the case of having a few tickets in time for that area of the code and > not reworking a few times the same docs. I suggest we still have the > labeling mentioned. It sounds like a good idea to me. > > I am also +1 on Benjamin’s idea. > > On Mon, 10 Jan 2022 at 9:43, Benjamin Lerer <b.le...@gmail.com> wrote: > >> It seems to me that we could use that work to attract new contributors. >> If we provide some clear process and divide the work in small chunks we >> can advertise the work on Twitter to get some volunteers. :-) >> > > > >> >> >> Le lun. 10 janv. 2022 à 07:59, Anthony Grasso <anthony.gra...@gmail.com> >> a écrit : >> >>> Hi Stefan and Ekaterina, >>> >>> First point to note is CASSANDRA-16763 is now closed. A big thank you to >>> Lorina Poland for converting the Cassandra documentation from >>> reStructuredText to AsciiDoc and to Mick Semb Wever for working over the >>> holiday period to get the ticket over the line! We are now at a point where >>> we can start documentation back-porting work thanks to those efforts. >>> >>> I do like Stefan's idea of tagging tickets that had documentation >>> changes with a label like "need-docs-backported". As Ekaterina points >>> out, if we reopen old tickets, this would get confusing to people >>> unfamiliar with the documentation work going on. The alternative is to >>> create a new ticket for each old ticket. From a practical perspective, I >>> think labelling and reopening an old ticket is the lesser of two evils. >>> >>> However, we should approach this from the point of view of any other >>> piece of work in the project. That is, consider the case where ticket >>> CASSANDRA-xyz had a committed patch, was resolved, but was later found to >>> have an issue due to the implementation of a feature that was later added. >>> Would we reopen it to fix the problem or would we open a new ticket? Do we >>> have project guidelines around this? I would think in this scenario a new >>> ticket would be created? >>> >>> In anycase, I feel we need to resolve the issue on how to track the work >>> first before we figure out how to divide it up. >>> >>> Kind regards, >>> Anthony >>> >>> On Thu, 14 Oct 2021 at 02:57, Ekaterina Dimitrova <e.dimitr...@gmail.com> >>> wrote: >>> >>>> 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 >>>> > >>>> > >>>> >>>
