[DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Lorina Poland <lo...@datastax.com>]

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

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Ekaterina Dimitrova <e....@gmail.com>]

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....@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....@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 <an...@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....@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.miklosovic@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.grasso@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.dimitrova@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.miklosovic@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.dimitrova@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 <blerer@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 <
>>>> lorina@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-unsubscribe@cassandra.apache.org
>>>> > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
>>>> > > > >
>>>> > > > >
>>>> > > >
>>>> >
>>>> > ---------------------------------------------------------------------
>>>> > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>>>> > For additional commands, e-mail: dev-help@cassandra.apache.org
>>>> >
>>>> >
>>>>
>>>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Ekaterina Dimitrova <e....@gmail.com>]

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....@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 <an...@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....@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.miklosovic@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.grasso@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.dimitrova@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.miklosovic@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.dimitrova@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 <bl...@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 <
>>> lorina@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-unsubscribe@cassandra.apache.org
>>> > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
>>> > > > >
>>> > > > >
>>> > > >
>>> >
>>> > ---------------------------------------------------------------------
>>> > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>>> > For additional commands, e-mail: dev-help@cassandra.apache.org
>>> >
>>> >
>>>
>>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Benjamin Lerer <b....@gmail.com>]

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 <an...@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....@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.miklosovic@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 <an...@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.dimitrova@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.miklosovic@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.dimitrova@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 <bl...@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 <
>> lorina@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-unsubscribe@cassandra.apache.org
>> > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
>> > > > >
>> > > > >
>> > > >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
>> > For additional commands, e-mail: dev-help@cassandra.apache.org
>> >
>> >
>>
>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Anthony Grasso <an...@gmail.com>]

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....@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.miklosovic@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 <an...@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.dimitrova@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.miklosovic@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.dimitrova@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 <bl...@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 <
> lorina@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-unsubscribe@cassandra.apache.org
> > > > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > > > >
> > > > >
> > > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> > For additional commands, e-mail: dev-help@cassandra.apache.org
> >
> >
>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Ekaterina Dimitrova <e....@gmail.com>]

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.miklosovic@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 <an...@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....@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.miklosovic@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.dimitrova@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 <bl...@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 <lo...@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-unsubscribe@cassandra.apache.org
> > > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > > >
> > > >
> > >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> For additional commands, e-mail: dev-help@cassandra.apache.org
>
>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Stefan Miklosovic <st...@instaclustr.com>]

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 <an...@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....@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.miklosovic@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....@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 <bl...@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 <lo...@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-unsubscribe@cassandra.apache.org
> > > For additional commands, e-mail: dev-help@cassandra.apache.org
> > >
> > >
> >

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
For additional commands, e-mail: dev-help@cassandra.apache.org

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Anthony Grasso <an...@gmail.com>]

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....@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.miklosovic@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....@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 <bl...@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 <lo...@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-unsubscribe@cassandra.apache.org
> > For additional commands, e-mail: dev-help@cassandra.apache.org
> >
> >
>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Ekaterina Dimitrova <e....@gmail.com>]

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.miklosovic@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....@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 <bl...@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 <lo...@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-unsubscribe@cassandra.apache.org
> For additional commands, e-mail: dev-help@cassandra.apache.org
>
>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Stefan Miklosovic <st...@instaclustr.com>]

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....@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 <bl...@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 <lo...@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-unsubscribe@cassandra.apache.org
For additional commands, e-mail: dev-help@cassandra.apache.org

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Ekaterina Dimitrova <e....@gmail.com>]

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 <bl...@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 <lo...@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
> >
>

Re: [DISCUSS] Cleaning up docs, completing CASSANDRA-16763

[Benjamin Lerer <bl...@apache.org>]

Thanks Lorina for all your work.

+1 Your proposal makes sense to me.

Le mer. 6 oct. 2021 à 00:34, Lorina Poland <lo...@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
>