Forgot to mention in my last message, but I am now implementing the
automation for calcite-avatica and calcite-avatica-go
For those 2 repos, we never used a site branch as we usually push the
site after a release. If there are any small updates to the site that
occur after the release, we just built from master and pushed it as
there is usually no unreleased updates to the docs due to avatica not
having much updates. This is the same situation for avatica-go.
Therefore, for calcite-avatica and calcite-avatica-go, I plan to:
- Always build from master if there's an update to site.
- For a release, build from master and build the javadocs and publish.
I think this should we sufficient for our use-case for now and should
improve the release process and site publishing process significantly.
If we find edge cases in the future, we can deal with those at a later
time.
Please let me know what you guys think.
Francis
On 30/03/2022 4:21 am, Julian Hyde wrote:
I have never needed or wanted a versioned Javadoc URL for Calcite. Our
APIs tend to grow over time.
The only requirement I see is that we don’t pollute the javadoc/doc of
the latest released version with things that are not yet released. Which
would lead to two versions: latest release and head.
I can see that the implementation might be simpler if we have multiple
versions, but let’s be clear that that is not the requirement.
Julian
On Mar 29, 2022, at 6:49 AM, Fan Liya <liya.fa...@gmail.com> wrote:
I think it is a good idea to provide versioned JavaDocs.
However, even if we only provide the JavaDoc of the latest release,
there is no need to maintain two branches (IMHO),
because the processes of updating the website and JavaDoc are
relatively separate processes (according to [1]).
With a single branch, it is feasible to update the website regularly,
and update JavaDocs only at release times.
Best,
Liya Fan
[1]
https://github.com/apache/calcite/blob/a6a1e2cef332893fd90286098869c56529e052c3/site/README.md
Alessandro Solimando <alessandro.solima...@gmail.com> 于2022年3月29日周二
17:59写道：
Hello everyone,
I totally agree on automating the website publication and having a
single
branch, the less we do manually, the lower the chances to mess
something up.
I am also in favour of versioned docs in the website, it's confusing to
land on updated pages from an older context like a message from the ML.
Best regards,
Alessandro
On Tue, 29 Mar 2022 at 06:44, Francis Chuang <francischu...@apache.org
wrote:
Hey Julian,
All very good points. I can definitely see the utility of the
javadocs.
The analogue in Go would be godoc, with the difference being that the
godoc server automatically crawls the code across all versions to
generate the documentation.
As an example, see the godoc for protobuf [1]. There is a version
selector on the top left to look at the documentation for different
versions of the module / library in question.
You mentioned that you do not want to have a version string in the
URL.
Is there any particular reason for this? For example, if I were to end
up on the mailing list archives through a google search and there's a
message linking to the javadoc, it might be more helpful if the
javadoc
was linked to a particular version of the release so that the context
around the discussion at the time makes more sense.
We can have all javadocs for all releases of Calcite published and
have
a selector to jump between versions, similar to godoc, for example,
like
this javadoc for google cloud with a version selector on the bottom
right [2]. This would allow users to switch between different versions
and look at the version of the javadoc that's currently being used in
their project.
Regarding the documentation on the website itself, would it make sense
if we have a versioned copy for each release? Currently, we only
publish
the documentation for the latest release, so, if we were to look at
older messages from the mailing list and follow a link to the
documentation, the documentation could be incorrect or not relevant to
the message itself.
Maybe we can have a folder for each release? For example:
-
calcite.apache.org/docs/1.30.0/adapter.html#jdbc-connect-string-parameters
-
calcite.apache.org/docs/1.29.0/adapter.html#jdbc-connect-string-parameters
This would give each release their own documentation with a unique
path.
For the current unreleased version, we can still put it in version of
the next release:
calcite.apache.org/docs/1.31.0/adapter.html#jbc-connect-string-parameters
and
maybe have a message that says this is an unreleased version like
elasticsearch [3]. Links to this release's javadoc would work before
and
after the release and would never break.
The upside to this approach is that all documentation (even the
unreleased version) is published immediately, but they are versioned,
so
there is no confusion. It also means that users of Calcite master
would
be able to look at the docs online. This also simplifies the
deployment
of site as we no longer need the site branch: the website can just be
built from master.
Francis
[1] https://pkg.go.dev/google.golang.org/protobuf
[2] https://googleapis.dev/java/google-cloud-asset/latest/index.html
[3] https://www.elastic.co/guide/en/elastic-stack/master/index.html
