Re: [DISCUSSION] Shall we remove ant javadoc task?

[Miklosovic, Stefan]

You can play with this in

File -> Settings -> Editor -> Inspections -> Javadoc

HTML problems in Javadoc -> Severity: Error

This will mark invalid html rendering of Javadocs as errorneous.

There are other checkboxes as well. I am not saying it solves it all but there 
is some room for tweaking this if one wishes.


From: Ekaterina Dimitrova 
Sent: Monday, August 21, 2023 20:05
To: dev@cassandra.apache.org
Subject: Re: [DISCUSSION] Shall we remove ant javadoc task?

NetApp Security WARNING: This is an external email. Do not click links or open 
attachments unless you recognize the sender and know the content is safe.



My only slight concern is that almost all the errors fixed in CASSANDRA-18717 
are such that they don’t trigger error or warning in the IDE. This means people 
will realize there is something to be done differently around javadoc only 
after they run the check task. I figured that before we commit to anything, it 
is good this point to be shared for visibility.
Maxim highlighted for me that this is already the case with some of the other 
checks we already have added with checkstyle. He looks into the problem in 
CASSANDRA-18277, mentioning here in case there are committers with cycles to 
help push it through

On Thu, 17 Aug 2023 at 12:46, Mick Semb Wever 
mailto:m...@apache.org>> wrote:
+1 to `ant check` (and to failing on it).

On Thu, 17 Aug 2023 at 18:43, Ekaterina Dimitrova 
mailto:e.dimitr...@gmail.com>> wrote:
Agreed with Maxim. If we fail CI on the javadoc task, in my opinion it should 
be added to ant check probably.

On Thu, 17 Aug 2023 at 12:40, Maxim Muzafarov 
mailto:mmu...@apache.org>> wrote:
We have "artifacts" ant target that depends on "checks" and "gen-doc",
from my point of view, it would be nice to have the "artifacts"
depending on "javadocs" as well. That way we can be sure that
everything related is in good order.

On Thu, 17 Aug 2023 at 18:05, Brandon Williams 
mailto:dri...@gmail.com>> wrote:
>
> If everything is good now, I think CI should fail if it regresses so
> we can keep it this way.
>
> Kind Regards,
> Brandon
>
> On Thu, Aug 17, 2023 at 10:49 AM Ekaterina Dimitrova
> mailto:e.dimitr...@gmail.com>> wrote:
> >
> > In CASSANDRA-18717 Maxim posted the javadoc fix. Stefan already made a 
> > first pass of review so it seems we are not removing this ant task as it 
> > was already fixed and there are people who find value of keeping it.
> > My question is do we want to fail CI if this regress or not?
> >
> > On Thu, 3 Aug 2023 at 22:44, Josh McKenzie 
> > mailto:jmcken...@apache.org>> wrote:
> >>
> >> the problem is that the javadoc task is not given the attention
> >> it deserves. The failonerror is currently 'false' and the task itself
> >> is not a part of any build and/or release processes
> >>
> >>
> >> I just wrote a tool that explores the distribution of keys across multiple 
> >> sstables, I needed some of the tools classes but not much more.  Javadocs 
> >> would have made that easy
> >>
> >> You know what? I agree with all that. If I had to jump into the source for 
> >> the JDK or other libraries every time I needed to work with them that'd be 
> >> annoying.
> >>
> >> BTW, I have managed to fix all the javadoc errors.
> >>
> >> Of course you have. :) Industrious as usual Maxim; thanks for tackling 
> >> that!
> >>
> >> So yeah. Depending on how long javadocs take to generate, I think having 
> >> them as part of our pre-commit rotation makes sense. Could even add them 
> >> to our site with something like an "API" section (gasp) here: 
> >> https://cassandra.apache.org/doc/latest/.
> >>
> >> Would certainly help motivate us to clarify the whole "what is an external 
> >> API we're committing to or not" discussions.
> >>
> >> On Thu, Aug 3, 2023, at 6:09 PM, Ekaterina Dimitrova wrote:
> >>
> >> Thank you Maxim. There is CASSANDRA-18717, I guess that patch should go 
> >> there. Keeping the task or not, the fix of the docs should go in anyway 
> >> IMHO. I will not be available the next few days, but I can help with 
> >> reviews when I am back.
> >>
> >> On Thu, 3 Aug 2023 at 17:44, Maxim Muzafarov 
> >> mailto:mmu...@apache.org>> wrote:
> >>
> >> Yes, I agree. The javadoc task should be part of our CI if we decide
> >> to keep it, to keep it buildable at all times.
> >>
> >>
> >> BTW, I have managed to fix all the javadoc errors.
> >> I have tested the task for both jdk11 and jdk17.
> >>
> >> Changes are here:
> >> https://github.com/apache/cassandra/compare/trunk...Mmuzaf:cassandra:javadoc_build

[DISCUSSION] News and announcements, help needed

[Ekaterina Dimitrova]

Hey friends,
The 5.0 alpha test build is out for testing! Great! Did you also have the
chance to attend any of the latest town halls?

Ok, it is time to say where I am going with this short intro...
Our friends from Constantia are working hard to help us spread the news and
promote all the great work we do in this community. They open Jira tickets
and PRs (not more than 1-2 per week, if any) to add announcements around
events, new features, town hall replays, etc. on the Cassandra website. It
requires a committer to do the review and push things through. The
publishing process on the Cassandra website underwent certain
transformations, and now it requires less effort (more on that below). I
wanted to raise the visibility and ask for committers' involvement; if you
see a ticket/PR and have 15 minutes, please, try to push it through.
Currently, some PRs can take up to 10 days to get committed. Is it possible
to cut that to 5 so we can spread any news on time?

For example, what it took me to correct a page on the website the other
week:

We have pre-commit CI in GitHub for cassandra-website commits; for example,
in CASSANDRA-18618 in my fork, the commits had checks like this:
https://github.com/ekaterinadimitrova2/cassandra-website/actions/runs/5825288289/job/15796474462

And it generates a (just top-level) website in the _generated branch, e.g.,
https://github.com/ekaterinadimitrova2/cassandra-website/blob/18738-trunk_generated/content/_/development/how_to_commit.html

I can take the raw URL of that and put it into raw.githack.com, e.g.,
https://raw.githack.com/ekaterinadimitrova2/cassandra-website/18738-trunk_generated/content/_/development/how_to_commit.html
to preview the generated output.

The rest is as before - we stage the changes and then push them live when
Jenkins completes. (full details in the website readme, I will also be
happy to guide anyone who is looking to lend a hand with this effort)

Feel free to let me know if you have any questions, concerns, or
suggestions to improve the process. Most discussions around the website
happen in ASF Slack #cassandra-website.

See you at the town hall on Thursday! :-)


Best regards,

Ekaterina

Re: [DISCUSSION] Shall we remove ant javadoc task?

[Ekaterina Dimitrova]

My only slight concern is that almost all the errors fixed in
CASSANDRA-18717 are such that they don’t trigger error or warning in the
IDE. This means people will realize there is something to be done
differently around javadoc only after they run the check task. I figured
that before we commit to anything, it is good this point to be shared for
visibility.
Maxim highlighted for me that this is already the case with some of the
other checks we already have added with checkstyle. He looks into the
problem in CASSANDRA-18277, mentioning here in case there are committers
with cycles to help push it through

On Thu, 17 Aug 2023 at 12:46, Mick Semb Wever  wrote:

> +1 to `ant check` (and to failing on it).
>
> On Thu, 17 Aug 2023 at 18:43, Ekaterina Dimitrova 
> wrote:
>
>> Agreed with Maxim. If we fail CI on the javadoc task, in my opinion it
>> should be added to ant check probably.
>>
>> On Thu, 17 Aug 2023 at 12:40, Maxim Muzafarov  wrote:
>>
>>> We have "artifacts" ant target that depends on "checks" and "gen-doc",
>>> from my point of view, it would be nice to have the "artifacts"
>>> depending on "javadocs" as well. That way we can be sure that
>>> everything related is in good order.
>>>
>>> On Thu, 17 Aug 2023 at 18:05, Brandon Williams  wrote:
>>> >
>>> > If everything is good now, I think CI should fail if it regresses so
>>> > we can keep it this way.
>>> >
>>> > Kind Regards,
>>> > Brandon
>>> >
>>> > On Thu, Aug 17, 2023 at 10:49 AM Ekaterina Dimitrova
>>> >  wrote:
>>> > >
>>> > > In CASSANDRA-18717 Maxim posted the javadoc fix. Stefan already made
>>> a first pass of review so it seems we are not removing this ant task as it
>>> was already fixed and there are people who find value of keeping it.
>>> > > My question is do we want to fail CI if this regress or not?
>>> > >
>>> > > On Thu, 3 Aug 2023 at 22:44, Josh McKenzie 
>>> wrote:
>>> > >>
>>> > >> the problem is that the javadoc task is not given the attention
>>> > >> it deserves. The failonerror is currently 'false' and the task
>>> itself
>>> > >> is not a part of any build and/or release processes
>>> > >>
>>> > >>
>>> > >> I just wrote a tool that explores the distribution of keys across
>>> multiple sstables, I needed some of the tools classes but not much more.
>>> Javadocs would have made that easy
>>> > >>
>>> > >> You know what? I agree with all that. If I had to jump into the
>>> source for the JDK or other libraries every time I needed to work with them
>>> that'd be annoying.
>>> > >>
>>> > >> BTW, I have managed to fix all the javadoc errors.
>>> > >>
>>> > >> Of course you have. :) Industrious as usual Maxim; thanks for
>>> tackling that!
>>> > >>
>>> > >> So yeah. Depending on how long javadocs take to generate, I think
>>> having them as part of our pre-commit rotation makes sense. Could even add
>>> them to our site with something like an "API" section (gasp) here:
>>> https://cassandra.apache.org/doc/latest/.
>>> > >>
>>> > >> Would certainly help motivate us to clarify the whole "what is an
>>> external API we're committing to or not" discussions.
>>> > >>
>>> > >> On Thu, Aug 3, 2023, at 6:09 PM, Ekaterina Dimitrova wrote:
>>> > >>
>>> > >> Thank you Maxim. There is CASSANDRA-18717, I guess that patch
>>> should go there. Keeping the task or not, the fix of the docs should go in
>>> anyway IMHO. I will not be available the next few days, but I can help with
>>> reviews when I am back.
>>> > >>
>>> > >> On Thu, 3 Aug 2023 at 17:44, Maxim Muzafarov 
>>> wrote:
>>> > >>
>>> > >> Yes, I agree. The javadoc task should be part of our CI if we decide
>>> > >> to keep it, to keep it buildable at all times.
>>> > >>
>>> > >>
>>> > >> BTW, I have managed to fix all the javadoc errors.
>>> > >> I have tested the task for both jdk11 and jdk17.
>>> > >>
>>> > >> Changes are here:
>>> > >>
>>> https://github.com/apache/cassandra/compare/trunk...Mmuzaf:cassandra:javadoc_build
>>> > >>
>>> > >> On Thu, 3 Aug 2023 at 21:20, Ekaterina Dimitrova <
>>> e.dimitr...@gmail.com> wrote:
>>> > >> >
>>> > >> > Thank you Maxim,
>>> > >> >
>>> > >> > “
>>> > >> >
>>> > >> > From my point of
>>> > >> > view, the problem is that the javadoc task is not given the
>>> attention
>>> > >> > it deserves. The failonerror is currently 'false' and the task
>>> itself
>>> > >> > is not a part of any build and/or release processes, correct me
>>> if I'm
>>> > >> > wrong.
>>> > >> >
>>> > >> > So,
>>> > >> > 1. Fix warnings/errors;
>>> > >> > 2. Make the javadoc task part of the build (e.g. put it under
>>> > >> > 'artifacts'), or make it part of the release process that is
>>> regularly
>>> > >> > checked on the CI;
>>> > >> > 3. Publish/deploy the javadoc htmls for release in the special
>>> > >> > directory of the cassandra website to give them a chance of being
>>> > >> > indexed;“
>>> > >> >
>>> > >> > This is aligned with what I saw and the two options mentioned at
>>> the beginning - if we decide to keep it we should fix things and add the
>>> task to CI,

[ANNOUNCE] Apache Cassandra 5.0-alpha1 test artifact available

[Mick Semb Wever]

The test build of Cassandra 5.0-alpha1 is available.

DISCLAIMER this alpha release does not contain the expected 5.0
features: Vector Search (CEP-30), Transactional Cluster Metadata
(CEP-21) and Accord Transactions (CEP-15).  These features will land
in a later alpha release.

sha1: 62cb03cc7311384db6619a102d1da6a024653fa6
Git: https://github.com/apache/cassandra/tree/5.0-alpha1-tentative
Maven Artifacts:
https://repository.apache.org/content/repositories/orgapachecassandra-1314/org/apache/cassandra/cassandra-all/5.0-alpha1/

The Source and Build Artifacts, and the Debian and RPM packages and
repositories, are available here:
https://dist.apache.org/repos/dist/dev/cassandra/5.0-alpha1/

A vote of this test build will be initiated within the next couple of days.

[1]: CHANGES.txt:
https://github.com/apache/cassandra/blob/5.0-alpha1-tentative/CHANGES.txt
[2]: NEWS.txt: 
https://github.com/apache/cassandra/blob/5.0-alpha1-tentative/NEWS.txt