In general, I prefer the Javadocs to reflect the latest release. I find
that when pulling dependencies into my projects (in languages such as
Go, Javascript, PHP, etc), I tend to pin to the latest release, unless
there's a critical and unreleased change on master that I really need.
I've been burnt in the past where generated documentation is for master
and not the latest release, causing some confusion.
On 16/07/2019 4:35 am, Julian Hyde wrote:
On Jul 14, 2019, at 3:27 PM, Francis Chuang <[email protected]> wrote:
In the past, the Javadocs were only ever built right after finalizing a
release. So, in general, the javadocs do not reflect snapshot versions.
Can Julian confirm if the javadocs must be for the latest final release?
That has been the policy. I don’t think we ever debated it. We can of course we
can debate it.
Remember that “snapshot versions” are not releases, and we should not encourage
people to believe that the code in Github’s master branch is approved.
The policy has been that the web site contains documentation and API docs for
the latest release. So, the release manager would roll out the site immediately
after a release is final. Other aspects of the web site (e.g. committer list,
upcoming talks, and process documents) are changed as and when needed. I
believe that is the most useful thing for our users.
Julian
