You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@activemq.apache.org by Clebert Suconic <cl...@gmail.com> on 2022/09/28 16:12:50 UTC
[DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Can we stop publishing javadocs on the ActiveMQ Website for artemis?
I see no point on publishing it as they are available in Maven.
My vote is to completely remove it.
So, if you agree with me, please respond with
+1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
and keep them on maven as usual.
if you have any other preferences please state a -1 and a reason for..
--
Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Robbie Gemmell <ro...@gmail.com>.
Personally I read most javadocs in the IDE these days whilst using the
thing in question, with IDEs grabbing it (/the source) from Maven
Central as you say. For more specific things about the actual client
or broker however I tend to link into their source on github these
days. I dont really ever look at or reference their javadoc on the
site.
It certainly bloats the site build a bunch by being there, I resorted
to adding a 'subset build config' to help knock say 20sec off refresh
builds while updating the newer content, but it would be nicer if it
simply wasnt as necessary.
All in all I dont see a great need for the javadoc to be on the
website these days, so I'd be fine with it not being there, +1
On Wed, 28 Sept 2022 at 17:13, Clebert Suconic
<cl...@gmail.com> wrote:
>
> Can we stop publishing javadocs on the ActiveMQ Website for artemis?
>
> I see no point on publishing it as they are available in Maven.
>
> My vote is to completely remove it.
>
>
> So, if you agree with me, please respond with
>
> +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> and keep them on maven as usual.
>
>
>
> if you have any other preferences please state a -1 and a reason for..
>
>
>
> --
> Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Robbie Gemmell <ro...@gmail.com>.
I have removed all the non-current Artemis javadocs leaving only the
'latest' ones (currently for 2.26.0), just as there are only 'latest'
ones for 5.x.
Since this change speeds up the full site serve.sh / build.sh
processes a fair bit, I decided to use that offset and also modify the
serve_subset.sh version to exclude all the javadoc entirely to speed
it up further too. This gets the subset rebuilds down to about 1
second which will make it a lot nicer to work on general site changes.
On Wed, 5 Oct 2022 at 18:45, Robbie Gemmell <ro...@gmail.com> wrote:
>
> JB, are your thoughts on this more general, i.e also applying to the
> 5.x 'latest' (typically stale) javadocs on the website as well, rather
> than just the per-release Artemis javadocs this thread started about?
>
> If so it would seem to me that all the people who regularly update the
> website bits for releases etc dont think we should bother having them
> there anymore.
>
> On Thu, 29 Sept 2022 at 20:10, Jean-Baptiste Onofré <jb...@nanthrax.net> wrote:
> >
> > Hi Clebert,
> >
> > I'm +1 about this for the two reasons:
> >
> > 1. I don't think lot of people read the Javadoc on website (personally
> > I'm reading directly in the IDE)
> > 2. We can still have the javadoc jar published on Maven (not need to
> > update website)
> >
> > Regards
> > JB
> >
> > On Wed, Sep 28, 2022 at 6:12 PM Clebert Suconic
> > <cl...@gmail.com> wrote:
> > >
> > > Can we stop publishing javadocs on the ActiveMQ Website for artemis?
> > >
> > > I see no point on publishing it as they are available in Maven.
> > >
> > > My vote is to completely remove it.
> > >
> > >
> > > So, if you agree with me, please respond with
> > >
> > > +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> > > and keep them on maven as usual.
> > >
> > >
> > >
> > > if you have any other preferences please state a -1 and a reason for..
> > >
> > >
> > >
> > > --
> > > Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Robbie Gemmell <ro...@gmail.com>.
JB, are your thoughts on this more general, i.e also applying to the
5.x 'latest' (typically stale) javadocs on the website as well, rather
than just the per-release Artemis javadocs this thread started about?
If so it would seem to me that all the people who regularly update the
website bits for releases etc dont think we should bother having them
there anymore.
On Thu, 29 Sept 2022 at 20:10, Jean-Baptiste Onofré <jb...@nanthrax.net> wrote:
>
> Hi Clebert,
>
> I'm +1 about this for the two reasons:
>
> 1. I don't think lot of people read the Javadoc on website (personally
> I'm reading directly in the IDE)
> 2. We can still have the javadoc jar published on Maven (not need to
> update website)
>
> Regards
> JB
>
> On Wed, Sep 28, 2022 at 6:12 PM Clebert Suconic
> <cl...@gmail.com> wrote:
> >
> > Can we stop publishing javadocs on the ActiveMQ Website for artemis?
> >
> > I see no point on publishing it as they are available in Maven.
> >
> > My vote is to completely remove it.
> >
> >
> > So, if you agree with me, please respond with
> >
> > +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> > and keep them on maven as usual.
> >
> >
> >
> > if you have any other preferences please state a -1 and a reason for..
> >
> >
> >
> > --
> > Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by "Tetreault, Lucas" <te...@amazon.com.INVALID>.
+1
I've never used the javadocs on the website and as Robbie said it makes building the site incredibly slow so testing changes locally is really painful. At the very least, it would be great to host them separately outside of the Jekyll website.
- Lucas
On 2022-09-29, 12:11 PM, "Jean-Baptiste Onofré" <jb...@nanthrax.net> 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.
Hi Clebert,
I'm +1 about this for the two reasons:
1. I don't think lot of people read the Javadoc on website (personally
I'm reading directly in the IDE)
2. We can still have the javadoc jar published on Maven (not need to
update website)
Regards
JB
On Wed, Sep 28, 2022 at 6:12 PM Clebert Suconic
<cl...@gmail.com> wrote:
>
> Can we stop publishing javadocs on the ActiveMQ Website for artemis?
>
> I see no point on publishing it as they are available in Maven.
>
> My vote is to completely remove it.
>
>
> So, if you agree with me, please respond with
>
> +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> and keep them on maven as usual.
>
>
>
> if you have any other preferences please state a -1 and a reason for..
>
>
>
> --
> Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
Hi Clebert,
I'm +1 about this for the two reasons:
1. I don't think lot of people read the Javadoc on website (personally
I'm reading directly in the IDE)
2. We can still have the javadoc jar published on Maven (not need to
update website)
Regards
JB
On Wed, Sep 28, 2022 at 6:12 PM Clebert Suconic
<cl...@gmail.com> wrote:
>
> Can we stop publishing javadocs on the ActiveMQ Website for artemis?
>
> I see no point on publishing it as they are available in Maven.
>
> My vote is to completely remove it.
>
>
> So, if you agree with me, please respond with
>
> +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> and keep them on maven as usual.
>
>
>
> if you have any other preferences please state a -1 and a reason for..
>
>
>
> --
> Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Robbie Gemmell <ro...@gmail.com>.
That would also be nicer than having them all, though still the same
amount of work on updates. Its what the 5.x docs at least aim to do
(typically out of date).
Another middle ground might be just automating the release details
linking to the zips on maven-central, meaning its still/actually
referenced from the site for those that look, but doesnt take any
specific effort/space/build-time etc.
On Wed, 28 Sept 2022 at 20:06, Clebert Suconic
<cl...@gmail.com> wrote:
>
> *if* we keep the javadoc, I would like to only keep the latest
> version.... I don't see much point on keeping 24+ versions of the
> javadocs
>
> On Wed, Sep 28, 2022 at 2:12 PM Étienne Hossack <ac...@hossack.me> wrote:
> >
> > -1
> >
> > Reasons to keep:
> > * It's useful to be able to link a specific line/method in the javadoc when explaining something to someone through the use of a URL
> > * It's nice to be able to navigate the source code in your browser, if say your IDE is having issues and you can't correctly navigate to docs via sources
> > * Often times you can read the ActiveMQ Artemis docs and think you understand a concept, but figuring out how to actually write the code to do it is pretty different - especially when the docs go out of date.
> >
> > In fact I'd rather the docs continue to reference the source code even more.
> >
> > If it's a lot of effort to maintain the publishing, I would reconsider for sure my stance, but as it stands, think it's pretty useful, and when my org isn't rate-limited on the apache website, I use them :'-)
> >
> > --
> > Étienne
> >
> > On Wed, 28 Sep 2022, at 9:12 AM, Clebert Suconic wrote:
> > > Can we stop publishing javadocs on the ActiveMQ Website for artemis?
> > >
> > > I see no point on publishing it as they are available in Maven.
> > >
> > > My vote is to completely remove it.
> > >
> > >
> > > So, if you agree with me, please respond with
> > >
> > > +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> > > and keep them on maven as usual.
> > >
> > >
> > >
> > > if you have any other preferences please state a -1 and a reason for..
> > >
> > >
> > >
> > > --
> > > Clebert Suconic
>
>
>
> --
> Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Clebert Suconic <cl...@gmail.com>.
*if* we keep the javadoc, I would like to only keep the latest
version.... I don't see much point on keeping 24+ versions of the
javadocs
On Wed, Sep 28, 2022 at 2:12 PM Étienne Hossack <ac...@hossack.me> wrote:
>
> -1
>
> Reasons to keep:
> * It's useful to be able to link a specific line/method in the javadoc when explaining something to someone through the use of a URL
> * It's nice to be able to navigate the source code in your browser, if say your IDE is having issues and you can't correctly navigate to docs via sources
> * Often times you can read the ActiveMQ Artemis docs and think you understand a concept, but figuring out how to actually write the code to do it is pretty different - especially when the docs go out of date.
>
> In fact I'd rather the docs continue to reference the source code even more.
>
> If it's a lot of effort to maintain the publishing, I would reconsider for sure my stance, but as it stands, think it's pretty useful, and when my org isn't rate-limited on the apache website, I use them :'-)
>
> --
> Étienne
>
> On Wed, 28 Sep 2022, at 9:12 AM, Clebert Suconic wrote:
> > Can we stop publishing javadocs on the ActiveMQ Website for artemis?
> >
> > I see no point on publishing it as they are available in Maven.
> >
> > My vote is to completely remove it.
> >
> >
> > So, if you agree with me, please respond with
> >
> > +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> > and keep them on maven as usual.
> >
> >
> >
> > if you have any other preferences please state a -1 and a reason for..
> >
> >
> >
> > --
> > Clebert Suconic
--
Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Robbie Gemmell <ro...@gmail.com>.
On Wed, 28 Sept 2022 at 19:12, Étienne Hossack <ac...@hossack.me> wrote:
>
> -1
>
> Reasons to keep:
> * It's useful to be able to link a specific line/method in the javadoc when explaining something to someone through the use of a URL
> * It's nice to be able to navigate the source code in your browser, if say your IDE is having issues and you can't correctly navigate to docs via sources
The Artemis javadocs dont include the HTML source code (I recently
removed it from the 5.x javadoc also via
https://issues.apache.org/jira/browse/AMQ-9074).
If wanting to 'browse' source code, looking at the actual code via the
GitHub or gitbox UIs tends to be more useful I find. You can also link
to javadoc source that way if needed.
> * Often times you can read the ActiveMQ Artemis docs and think you understand a concept, but figuring out how to actually write the code to do it is pretty different - especially when the docs go out of date.
>
Javadoc can often go nearly as out of date as standalone docs too,
I've lost count of the number of times I note javadocs were not
properly updated to reflect a code change in a PR.
If writing code using something, many will typically then have it in
an IDE that then has/gets the sources (and javadoc).
> In fact I'd rather the docs continue to reference the source code even more.
>
> If it's a lot of effort to maintain the publishing, I would reconsider for sure my stance, but as it stands, think it's pretty useful, and when my org isn't rate-limited on the apache website, I use them :'-)
>
It slows down building the site no end, publishing the site somewhat,
uses a chunk of space, and adds a step to doing the release updates.
The latter is perhaps why 5.x releases mostly seem to skip updating
the hosted javadoc. It was missing entirely for about a year after the
site content moved before anyone (a committer) noticed. It wasnt then
updated for another 3 years after that, missing 5.16.x entirely, and
hasnt been updated for the couple releases in the past 6 months. To be
fair there probably hasnt been much change.
> --
> Étienne
>
> On Wed, 28 Sep 2022, at 9:12 AM, Clebert Suconic wrote:
> > Can we stop publishing javadocs on the ActiveMQ Website for artemis?
> >
> > I see no point on publishing it as they are available in Maven.
> >
> > My vote is to completely remove it.
> >
> >
> > So, if you agree with me, please respond with
> >
> > +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> > and keep them on maven as usual.
> >
> >
> >
> > if you have any other preferences please state a -1 and a reason for..
> >
> >
> >
> > --
> > Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Étienne Hossack <ac...@hossack.me>.
-1
Reasons to keep:
* It's useful to be able to link a specific line/method in the javadoc when explaining something to someone through the use of a URL
* It's nice to be able to navigate the source code in your browser, if say your IDE is having issues and you can't correctly navigate to docs via sources
* Often times you can read the ActiveMQ Artemis docs and think you understand a concept, but figuring out how to actually write the code to do it is pretty different - especially when the docs go out of date.
In fact I'd rather the docs continue to reference the source code even more.
If it's a lot of effort to maintain the publishing, I would reconsider for sure my stance, but as it stands, think it's pretty useful, and when my org isn't rate-limited on the apache website, I use them :'-)
--
Étienne
On Wed, 28 Sep 2022, at 9:12 AM, Clebert Suconic wrote:
> Can we stop publishing javadocs on the ActiveMQ Website for artemis?
>
> I see no point on publishing it as they are available in Maven.
>
> My vote is to completely remove it.
>
>
> So, if you agree with me, please respond with
>
> +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> and keep them on maven as usual.
>
>
>
> if you have any other preferences please state a -1 and a reason for..
>
>
>
> --
> Clebert Suconic
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Matt Pavlovich <ma...@gmail.com>.
My $0.02. I’m in favor of hosting javadocs. It is a low effort form of documentation that can fill gaps for configuration options and default values where other forms of docs may not keep up.
I’m in favor at minimum the ‘latest’ version of the javadocs for all active (or LTS-style) release branches. Older versions will age out and can leverage maven repo for archive.
Thanks,
Matt Pavlovich
> On Sep 28, 2022, at 2:32 PM, Justin Bertram <jb...@apache.org> wrote:
>
> This got me thinking about who is the intended audience for the JavaDoc.
> It's not for folks working on the broker directly since they already have
> the source code and can read the JavaDoc directly. It's not for folks using
> JMS, AMQP, OpenWire, MQTT, or STOMP since the JavaDoc doesn't apply to any
> of those. From what I can tell, the JavaDoc is *only* for users leveraging
> the core client which is quite a small group and even those folks will
> almost certainly be using it in an IDE which can display it.
>
> I'm +1 to remove it, but if we do keep it then we should do something
> smarter like only publish it when something changes (e.g. methods are
> deprecated or added).
>
>
> Justin
>
> On Wed, Sep 28, 2022 at 11:18 AM Clebert Suconic <cl...@gmail.com>
> wrote:
>
>> Can we stop publishing javadocs on the ActiveMQ Website for artemis?
>>
>> I see no point on publishing it as they are available in Maven.
>>
>> My vote is to completely remove it.
>>
>>
>> So, if you agree with me, please respond with
>>
>> +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
>> and keep them on maven as usual.
>>
>>
>>
>> if you have any other preferences please state a -1 and a reason for..
>>
>>
>>
>> --
>> Clebert Suconic
>>
>>
Re: [DISCUSS/VOTE] Remove Artemis Javadoc from the ActiveMQ website...
Posted by Justin Bertram <jb...@apache.org>.
This got me thinking about who is the intended audience for the JavaDoc.
It's not for folks working on the broker directly since they already have
the source code and can read the JavaDoc directly. It's not for folks using
JMS, AMQP, OpenWire, MQTT, or STOMP since the JavaDoc doesn't apply to any
of those. From what I can tell, the JavaDoc is *only* for users leveraging
the core client which is quite a small group and even those folks will
almost certainly be using it in an IDE which can display it.
I'm +1 to remove it, but if we do keep it then we should do something
smarter like only publish it when something changes (e.g. methods are
deprecated or added).
Justin
On Wed, Sep 28, 2022 at 11:18 AM Clebert Suconic <cl...@gmail.com>
wrote:
> Can we stop publishing javadocs on the ActiveMQ Website for artemis?
>
> I see no point on publishing it as they are available in Maven.
>
> My vote is to completely remove it.
>
>
> So, if you agree with me, please respond with
>
> +1 Yes, stop publishing javadocs for ActiveMQ Artemis on the website
> and keep them on maven as usual.
>
>
>
> if you have any other preferences please state a -1 and a reason for..
>
>
>
> --
> Clebert Suconic
>
>