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
