Re: [DISCUSS] Documentation donation

[Jon Haddad]

We've already got Sphinx set up, so you can contribute today.  There's a
docker container in the `docs` directory and a readme that can help you get
started.

On Fri, May 1, 2020 at 10:46 AM Chen-Becker, Derek
 wrote:

>  From the peanut gallery, my main concern is less with the features of a
> given markup and more with ensuring that whatever markup/doc system is
> used stays mostly out of the way of people who want to contribute to the
> docs. I don't want to have to learn a whole publishing system just to be
> able to contribute, whereas minor differences in markup syntax seem
> reasonable. Whatever system ends up getting chosen, is there additional
> work that can be done to simplify work for writers? I've used all three
> (albeit not in-depth), so I'm willing to help.
>
> Derek
>
> On 5/1/20 11:08 AM, Jon Haddad wrote:
>
> > CAUTION: This email originated from outside of the organization. Do not
> click links or open attachments unless you can confirm the sender and know
> the content is safe.
> >
> >
> >
> > Apologies, I didn't mean to upset or insult you.  My intent was to
> > demonstrate that my opinion is based on experience and I wasn't
> suggesting
> > we switch tooling based on a whim.  I also wasn't trying to imply you
> > aren't knowledgeable about writing documentation.
> >
> > Apart from this misunderstanding, I think we mostly agree.  I'm not
> looking
> > to perform a migration that removes functionality, and the features
> you've
> > listed are all important to keep.  Thanks for listing out the bits that
> are
> > more complex that I glossed over with my "We write basic text with links
> > and a menu" comment, that was clearly wrong and I appreciate the
> correction.
> >
> > Regarding the functionality you listed:
> >
> > * Note and warning are both useful features and come built into
> > asciidoctor.  I made use of them in the TLP documentation for tlp-cluster
> > [1]
> > * I believe the extlinks feature can be replicated easily using a macro.
> > Here's an example [2].
> > * The grammar is a bit more difficult and I don't think there's a drop in
> > replacement.  Writing a block processor [3] would be the right way to
> > approach it, I think.
> > * We'd probably want to set up a configuration for syntax highlighting
> via
> > highlight.js (or one of the other supported libs).  We can use the SQL
> one
> > [4] as a guide since it's going to be similar to what we need, and
> ideally
> > we would contribute it back for CQL support.
> >
> > I agree with you that any migration would at a *minimum* need the above
> > functionality to be on par with what we already have.  A POC in a branch
> > displaying a handful of pages (that work with the site theme, etc), one
> of
> > which is a converted DDL page [5] would suffice, I think, to assess
> whether
> > or not it's worth the effort.
> >
> > No matter which direction we end up going, we still need to get
> > documentation improvements in for 4.0, so it's probably worth focusing on
> > that now, and convert to adoc later.  I'm happy to get on a call soon
> with
> > folks who are new to the project documentation to answer any questions
> you
> > all may have.  I'm also available to review patches to the docs, just set
> > me as the reviewer and ping me on Slack.  I try to get to them within
> 24h.
> >
> > Jon
> >
> > [1] http://thelastpickle.com/tlp-cluster/#_setup
> > [2] https://markhneedham.com/blog/2018/02/19/asciidoctor-creating-macro/
> > [3]
> >
> https://github.com/asciidoctor/asciidoctorj/blob/v2.1.0/docs/integrator-guide.adoc#blockprocessor
> > [4]
> >
> https://github.com/highlightjs/highlight.js/blob/master/src/languages/sql.js
> > [5] https://cassandra.apache.org/doc/latest/cql/ddl.html
> >
> > On Thu, Apr 30, 2020 at 2:21 PM Sylvain Lebresne 
> wrote:
> >
> >> As I mentioned, I really have nothing against asciidoc. In fact, I think
> >> it's
> >> great.
> >>
> >> Let's just say that I think rst/sphinx is also pretty capable, and that
> I
> >> consider
> >> your characterization of the syntax difference (one "awful", the other
> "a
> >> dream") a tad over-the-top. I do agree on the point on documentation
> >> though,
> >> the asciidoc one is better (not that I find the rst one completely
> >> inadequate
> >> either), and I reckon it's a good argument.
> >>
> >> So to be clear, if someone makes the change to asciidoc and it's not
> >> botched, I
> >> won't personally stand in the way.
> >>
> >> I'll note however that asking we analyze the pros and cons of a change
> >> should not be seen as suspicious. And we should imo strive to justify
> any
> >> change with objective arguments. One's experience certainly increases
> the
> >> believability of one's arguments, but it doesn't dispense from
> presenting
> >> arguments in the first place.
> >>
> >> And I wish the substance of your previous email wasn't: I know, you
> don't,
> >> and
> >> the project don't have time to wait on you learning, so just trust me.
> >>
> >>> You're right 

Re: [DISCUSS] Documentation donation

[Chen-Becker, Derek]

From the peanut gallery, my main concern is less with the features of a 
given markup and more with ensuring that whatever markup/doc system is 
used stays mostly out of the way of people who want to contribute to the 
docs. I don't want to have to learn a whole publishing system just to be 
able to contribute, whereas minor differences in markup syntax seem 
reasonable. Whatever system ends up getting chosen, is there additional 
work that can be done to simplify work for writers? I've used all three 
(albeit not in-depth), so I'm willing to help.


Derek

On 5/1/20 11:08 AM, Jon Haddad wrote:


CAUTION: This email originated from outside of the organization. Do not click 
links or open attachments unless you can confirm the sender and know the 
content is safe.



Apologies, I didn't mean to upset or insult you.  My intent was to
demonstrate that my opinion is based on experience and I wasn't suggesting
we switch tooling based on a whim.  I also wasn't trying to imply you
aren't knowledgeable about writing documentation.

Apart from this misunderstanding, I think we mostly agree.  I'm not looking
to perform a migration that removes functionality, and the features you've
listed are all important to keep.  Thanks for listing out the bits that are
more complex that I glossed over with my "We write basic text with links
and a menu" comment, that was clearly wrong and I appreciate the correction.

Regarding the functionality you listed:

* Note and warning are both useful features and come built into
asciidoctor.  I made use of them in the TLP documentation for tlp-cluster
[1]
* I believe the extlinks feature can be replicated easily using a macro.
Here's an example [2].
* The grammar is a bit more difficult and I don't think there's a drop in
replacement.  Writing a block processor [3] would be the right way to
approach it, I think.
* We'd probably want to set up a configuration for syntax highlighting via
highlight.js (or one of the other supported libs).  We can use the SQL one
[4] as a guide since it's going to be similar to what we need, and ideally
we would contribute it back for CQL support.

I agree with you that any migration would at a *minimum* need the above
functionality to be on par with what we already have.  A POC in a branch
displaying a handful of pages (that work with the site theme, etc), one of
which is a converted DDL page [5] would suffice, I think, to assess whether
or not it's worth the effort.

No matter which direction we end up going, we still need to get
documentation improvements in for 4.0, so it's probably worth focusing on
that now, and convert to adoc later.  I'm happy to get on a call soon with
folks who are new to the project documentation to answer any questions you
all may have.  I'm also available to review patches to the docs, just set
me as the reviewer and ping me on Slack.  I try to get to them within 24h.

Jon

[1] http://thelastpickle.com/tlp-cluster/#_setup
[2] https://markhneedham.com/blog/2018/02/19/asciidoctor-creating-macro/
[3]
https://github.com/asciidoctor/asciidoctorj/blob/v2.1.0/docs/integrator-guide.adoc#blockprocessor
[4]
https://github.com/highlightjs/highlight.js/blob/master/src/languages/sql.js
[5] https://cassandra.apache.org/doc/latest/cql/ddl.html

On Thu, Apr 30, 2020 at 2:21 PM Sylvain Lebresne  wrote:


As I mentioned, I really have nothing against asciidoc. In fact, I think
it's
great.

Let's just say that I think rst/sphinx is also pretty capable, and that I
consider
your characterization of the syntax difference (one "awful", the other "a
dream") a tad over-the-top. I do agree on the point on documentation
though,
the asciidoc one is better (not that I find the rst one completely
inadequate
either), and I reckon it's a good argument.

So to be clear, if someone makes the change to asciidoc and it's not
botched, I
won't personally stand in the way.

I'll note however that asking we analyze the pros and cons of a change
should not be seen as suspicious. And we should imo strive to justify any
change with objective arguments. One's experience certainly increases the
believability of one's arguments, but it doesn't dispense from presenting
arguments in the first place.

And I wish the substance of your previous email wasn't: I know, you don't,
and
the project don't have time to wait on you learning, so just trust me.


You're right about markdown being a little limited, but we're not really
using anything advanced in sphinx. We write basic text with links and a

menu.

Not really true of at least the CQL section. It makes somewhat extensive
use
of the 'productionlist::' feature. Which gives us decent formatting of the
CQL
grammar elements "for free", automatic cross-referencing within said
grammar
and easy cross-referencing to said grammar from the rest of the text. I
think
that's kind of nice? I could be wrong, but getting the same even with
asciidoc
is going to be much more manual, and definitively would with markdown.

We also use 'note::' 

Re: [DISCUSS] Documentation donation

[Jon Haddad]

Apologies, I didn't mean to upset or insult you.  My intent was to
demonstrate that my opinion is based on experience and I wasn't suggesting
we switch tooling based on a whim.  I also wasn't trying to imply you
aren't knowledgeable about writing documentation.

Apart from this misunderstanding, I think we mostly agree.  I'm not looking
to perform a migration that removes functionality, and the features you've
listed are all important to keep.  Thanks for listing out the bits that are
more complex that I glossed over with my "We write basic text with links
and a menu" comment, that was clearly wrong and I appreciate the correction.

Regarding the functionality you listed:

* Note and warning are both useful features and come built into
asciidoctor.  I made use of them in the TLP documentation for tlp-cluster
[1]
* I believe the extlinks feature can be replicated easily using a macro.
Here's an example [2].
* The grammar is a bit more difficult and I don't think there's a drop in
replacement.  Writing a block processor [3] would be the right way to
approach it, I think.
* We'd probably want to set up a configuration for syntax highlighting via
highlight.js (or one of the other supported libs).  We can use the SQL one
[4] as a guide since it's going to be similar to what we need, and ideally
we would contribute it back for CQL support.

I agree with you that any migration would at a *minimum* need the above
functionality to be on par with what we already have.  A POC in a branch
displaying a handful of pages (that work with the site theme, etc), one of
which is a converted DDL page [5] would suffice, I think, to assess whether
or not it's worth the effort.

No matter which direction we end up going, we still need to get
documentation improvements in for 4.0, so it's probably worth focusing on
that now, and convert to adoc later.  I'm happy to get on a call soon with
folks who are new to the project documentation to answer any questions you
all may have.  I'm also available to review patches to the docs, just set
me as the reviewer and ping me on Slack.  I try to get to them within 24h.

Jon

[1] http://thelastpickle.com/tlp-cluster/#_setup
[2] https://markhneedham.com/blog/2018/02/19/asciidoctor-creating-macro/
[3]
https://github.com/asciidoctor/asciidoctorj/blob/v2.1.0/docs/integrator-guide.adoc#blockprocessor
[4]
https://github.com/highlightjs/highlight.js/blob/master/src/languages/sql.js
[5] https://cassandra.apache.org/doc/latest/cql/ddl.html

On Thu, Apr 30, 2020 at 2:21 PM Sylvain Lebresne  wrote:

> As I mentioned, I really have nothing against asciidoc. In fact, I think
> it's
> great.
>
> Let's just say that I think rst/sphinx is also pretty capable, and that I
> consider
> your characterization of the syntax difference (one "awful", the other "a
> dream") a tad over-the-top. I do agree on the point on documentation
> though,
> the asciidoc one is better (not that I find the rst one completely
> inadequate
> either), and I reckon it's a good argument.
>
> So to be clear, if someone makes the change to asciidoc and it's not
> botched, I
> won't personally stand in the way.
>
> I'll note however that asking we analyze the pros and cons of a change
> should not be seen as suspicious. And we should imo strive to justify any
> change with objective arguments. One's experience certainly increases the
> believability of one's arguments, but it doesn't dispense from presenting
> arguments in the first place.
>
> And I wish the substance of your previous email wasn't: I know, you don't,
> and
> the project don't have time to wait on you learning, so just trust me.
>
> > You're right about markdown being a little limited, but we're not really
> > using anything advanced in sphinx. We write basic text with links and a
> menu.
>
> Not really true of at least the CQL section. It makes somewhat extensive
> use
> of the 'productionlist::' feature. Which gives us decent formatting of the
> CQL
> grammar elements "for free", automatic cross-referencing within said
> grammar
> and easy cross-referencing to said grammar from the rest of the text. I
> think
> that's kind of nice? I could be wrong, but getting the same even with
> asciidoc
> is going to be much more manual, and definitively would with markdown.
>
> We also use 'note::' and 'warning::' boxes in a few places, and those are
> also
> nice to have imo, and I don't think mardown would give us that easily.
>
> We also define a jira "extlinks" (so that anywhere in the doc, ":jira:`42`"
> is
> replaced by a proper link named CASSANDRA-42 and pointing to that ticket)
> and
> it's used in a few places.
>
> Fwiw, it's this kind of things (and any future similar use we may want) I
> had
> in mind when discussing markdown being limited, and we can debate their
> importance, but we do use them.
>
> But maybe those don't qualify as "really" using advanced stuffs. How would
> I
> know, I'm the guy that needs to learn, you're the expert.
>
> --
> Sylvain
>
>
> On Thu, 

Re: 4-26-2020 update on Kubernetes Operator

[John Sanda]

Hi Deepak,

During the last SIG meetings, both repair and backup/restore were discussed
in the context of lifecycle management. The Instaclustr operator already
has backup/restore capabilities which are documented here
 (in full disclosure, I have never used the
operator, just aware of the feature). Medusa
 is another possibility.
There have been a couple discussions in tickets in the medusa repo. Just
wanted to point out that it is definitely on the radar.

On Thu, Apr 30, 2020 at 12:41 PM Deepak Vohra 
wrote:

>  Updated CEP-2:
> Without involving advanced automation that could involve resources
> specific to Cloud Service provider, the following could be added.
> - Automatic backup and restore operations-  Role-based access control
> (RBAC) Automated Security Management- Automated Monitoring Through
> Prometheus
> thanks,Deepak
> On Monday, April 27, 2020, 04:33:45 p.m. UTC, Stefan Miklosovic <
> stefan.mikloso...@instaclustr.com> wrote:
>
>  Hi Deepak,
>
> while we would be delighted to take Instaclustr's operator as a
> baseline, this is not so simple ...
>
> I think we should gather all functional requirements first, improve
> and complete the actual CEP and based on these facts we should distil
> the best solution, whatever it would be.
>
> In general, I do not want this whole operator effort to be about "ours
> or theirs" and "who wins", it should be done _together_. My take on
> this as of now is that let's forget about all operators and let's
> pretend we just want to build a new one. Based on what operator we
> want to have, after that we will look around and make some comparison
> to see what is already available among all operators out there. Based
> on that, we could cherry-pick features and approaches from each or
> introduce some completely different and only after that we would start
> to think about the implementation. I think we are just at the very
> beginning and I do not think that mentioning whatever operator at this
> moment is a good idea (but I am glad you are interested!).
>
> How does this sound to you? Do you think that you could be helpful
> with going through the CEP Patrick has compiled while adding more
> details and features you would like to see? That would be of
> tremendous help and we would know more in detail what we actually want
> and we can discuss it in more detail afterwards.
>
> Regards and thanks a lot in advance
>
> On Mon, 27 Apr 2020 at 17:16, Deepak Vohra 
> wrote:
> >
> >  An operator for Apache Cassandra in alpha is provided by Instaclustr
> that supports StatefulSet, scaling and monitoring. Could it be used as the
> base operator to build on? OperatorHub.io | The registry for Kubernetes
> Operators
> >
> > |
> > |
> > |  |
> > OperatorHub.io | The registry for Kubernetes Operators
> >
> > The registry for Kubernetes Operators
> >  |
> >
> >  |
> >
> >  |
> >
> >
> >
> >
> >
> >On Monday, April 27, 2020, 05:49:37 a.m. UTC, Patrick McFadin <
> pmcfa...@gmail.com> wrote:
> >
> >  *Hi everyone,Over the past two weeks, we have had 4 public meetings
> with a
> > lot of great discussions. You can find the recordings and notes here:
> >
> https://cwiki.apache.org/confluence/display/CASSANDRA/Cassandra+Kubernetes+Operator+SIG
> > <
> https://cwiki.apache.org/confluence/display/CASSANDRA/Cassandra+Kubernetes+Operator+SIG
> >There
> > were some important next steps after this week. First is some
> housekeeping.
> > Having two meetings allowed for better time zone spread, but the
> > discussions were disconnected and tended to be somewhat redundant. It was
> > suggested to move to a single meeting that can span the most timezones. I
> > took that feedback and have rebuilt the SIG meeting schedules in the same
> > type of rotation being used for the Contributor Meetings. We’ll see how
> > that goes for everyone effected. I’ve also switched away from Zoom to
> Jitsi
> > (jitsi.org ). Switching to a more open video
> conferencing
> > software seemed like a natural move and the feature list is comparable to
> > Zoom.All the meeting details and schedule are posted here:
> >
> https://cwiki.apache.org/confluence/display/CASSANDRA/Cassandra+Kubernetes+Operator+SIG
> > <
> https://cwiki.apache.org/confluence/display/CASSANDRA/Cassandra+Kubernetes+Operator+SIG
> >This
> > includes a calendar file and shared calendar link. Next important thing
> is
> > the beginning of the CEP for the Kubernetes Operator. Ben Bromhead and I
> > took a first pass at a skeleton for CEP-2
> > <
> https://cwiki.apache.org/confluence/display/CASSANDRA/CEP-2+Kubernetes+Operator
> >
> > with all the basics. At this point, we need everyone participating in the
> > project to take some time and help build out some of the critical
> details.
> > Because everyone loves Confluence so much, I have created a Google doc we
> > can use as a working area before moving over to a more formal Cassandra
> > 

Re: Staging website at cassandra.staged.apache.org

[Murukesh Mohanan]

For clarification, when you say "this would clean the master
branch history", would the content directory be removed from past commits
using bfg or similar tools?

(I'm fine with either way; just curious.)

On Fri, 1 May 2020, 07:12 Anthony Grasso,  wrote:

> Hi everyone,
>
> Thanks to hard work by Mick every push to the cassandra-website *src/*
> directory in master is now automatically deployed to
> https://cassandra.staged.apache.org/. The automation is carried out by a
> Jenkins job at https://ci-cassandra.apache.org/job/cassandra-website/.
> This
> is really useful because it allows us to preview our changes in the staging
> site before we push them to the production site!
>
> With the above change in place, the process to deploy a change to the
> production site is.
> 1. Commit your change to the *src/* directory in the master branch. Jenkins
> will now automatically generate the (HTML) site pages in *content/*
> directory on the asf-staging branch.
> 2. Preview your changes on the staging site:
> https://cassandra.staged.apache.org/.
> 3. If the changes look good, then merge the *content/* directory on the
> asf-staging branch to the master branch using:
>
>
> $ git merge asf-staging
> $ git push
>
>
> An issue with the above process is the master branch history is now going
> to get polluted with the auto-generated content commits. Even without the
> Jenkins automation, the process to publish to the production site still had
> the issue where commits to the master branch included both the *src/* and
> *content/* directory changes. A small one line change to the *src/*
> directory, could result in changes to hundreds of pages in the *content/*
> directory.
>
> Rather than serving the production site from the *content/* directory on
> the master branch, is there any objection to serving it from the asf-site
> branch? This would mean that the last step in the above process would be
> performed on the asf-site branch rather than the master branch. In
> addition, there would be no need to have a *content/* directory on the
> master branch. The *content/* directory from which the production site is
> served would live in the asf-site branch. This would clean the master
> branch history, hiding the generated *content/* directory and the unwieldy
> content changes generated by Jenkins user.
>
> Let me know what you think about the proposed change.
>
> Regards,
> Anthony
>
> On Tue, 21 Apr 2020 at 16:40, Mick Semb Wever  wrote:
>
> > For our cassandra-website repository, any changes to our website can now
> > first be staged at https://cassandra.staged.apache.org/
> >
> > The staged website comes from the content/ directory on the `asf-staging`
> > branch.
> >
> > regards,
> > Mick
> >
>